Documentation

  • About NetCloud API
  • Introduction
  • API Endpoint Reference
  • Sample Code
  • Usage Guidelines
  • Configuration

Cradlepoint NetCloud Manager NetCloud API Version 2

Cradlepoint NetCloud Manager (NCM) is a SaaS-type server that enables the remote management of network devices, including routers and access points. This specification describes the NetCloud API; a RESTful API used by client applications to access the NetCloud service and programmatically perform many of the same functions as can be performed in the NCM UI.

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

What is a REST API?

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

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

A REST API is a hypertext-driven API that uses HTTP methods and follows the REST principles. The Cradlepoint NetCloud Manager REST API uses the following HTTP methods: GET, POST, PUT, PATCH, and DELETE. Note that not all endpoints support all of the REST methods. Some endpoints are read-only and only support the GET method while other endpoints support a mix of all the methods.

Basics

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

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

Authorization: Authorization is the process of determining the actions a given user may take in NetCloud. The actions a user can take within NetCloud are based on the role assigned to that user. These roles are Administrator, Full Access User, Read Only User, or Diagnostic Uer.

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

Supported Security

In compliance with PCI 3.2, NetCloud API supports TLS v1.2 and 1.3. SSL and earlier versions of TLS are not supported. The following ciphers are supported:

TLS 1.3
          TLS_AES_128_GCM_SHA256
          TLS_AES_256_GCM_SHA384
          TLS_CHACHA20_POLY1305_SHA256
          TLS_AES_128_CCM_SHA256
          TLS_AES_128_CCM_8_SHA256
        

TLS 1.2

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

This section describes 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 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 to a different account, the request should 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, 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 '?'. 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 {paging}

Endpoints that return result sets with multiple records (lists) can be "paged" through by specifying 'offset' and 'limit' parameters.

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

The offset parameter is supported for the following endpoints:

  • routers
  • net_devices
  • groups
  • accounts
  • products
  • firmwares
  • net_device_metrics
  • configuration_manager

When a list of records 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. To page the whole list you need to increment the offset. So to get the next 25 devices:

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

{fields} aka Partial Returns

If the requestor does not want to get the full response body, they can use the _fields_ param to get a partial result containing only the specified fields. Example:

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

Sign in to your account for quick access to useful values.

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.

The accounts endpoint supports GET, POST, PUT, and DELETE methods.

  • Accounts Endpoint Fields and Filters
  • This table lists the fields associated with the accounts endpoint. Fields with operators specified in the Filter column indicate that those fields can be used as filters.

    Parameter Data Type Filter Sort Expand Description Permissions
    account*! url =, __in Parent account Read/Write
    id! int =, __in Object ID Read Only
    is_disabled bool True if the account is disabled Read Only
    name*! string =, __in Name of the account Read/Write
    resource_url url Object URL Read Only
    Note: * indicates the attribute is required in the request body for PUT and POST requests.
    Note: ! indicates the attribute is required for PUT request
  • Tips for Using the NetCloud API
  • When making API calls with curl in a console session, it can be helpful to define variables for your API keys, payloads, and the base URL of the endpoint for re-use with each curl statement.
    Please note that the method for setting variables in your console of choice can vary depending on the console/OS used. These variable definition examples are BASH specific; other console tools can require slightly different syntax to define these variables in a console session.

    • X_ECM_API_ID="<X-ECM-API-ID>"
    • X_ECM_API_KEY="<X-ECM-API-KEY>"
    • X_CP_API_ID="<X-CP-API-ID>"
    • X_CP_API_KEY="<X-CP-API-KEY>"
    • -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY"
    • URL="https://www.cradlepointecm.com/api/v2/accounts/"
    • BODY = -d '{"<field name>": "<field value>"}

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

  • GET Examples
  • Example curl GET request/response to the accounts endpoint without filters applied. This retrieves data about your primary, or "owning" account, and any nested subaccounts beneath your owning account.

    curl -H "X-ECM-API-ID: $X_ECM_API_ID" -H "X-ECM-API-KEY: $X_ECM_API_KEY" -H "X-CP-API-ID: $X_CP_API_ID" -H "X-CP-API-KEY: $X_CP_API_KEY" -H "Content-Type: application/json" -L $URL     
    

    Response body for curl GET example

          {            
        "data": [
            {
                "account": "https://www.cradlepointecm.com/api/v2/accounts/308/",
                "id": "241",
                "is_disabled": false,
                "name": "cradlepoint",
                "resource_url": "https://www.cradlepointecm.com/api/v2/accounts/241/"
            },
            {
                "account": "https://www.cradlepointecm.com/api/v2/accounts/123/",
                "id": "308",
                "is_disabled": false,
                "name": "root",
                "resource_url": "https://www.cradlepointecm.com/api/v2/accounts/308/"
            },
            { ... }
        ],
        "meta": {
            "limit": 20,
            "next": null,
            "offset": 0,
            "previous": null
        }
    }
             

    The following is an example of the URL to use with a curl GET request to the accounts endpoint using the name filter. Using this URL with the curl example above returns data about an account, and any subaccounts it owns, matching the key/value ?name=name in the query string.

    https://www.cradlepointecm.com/api/v2/accounts/?name=name

  • POST Examples
  • Use POST requests to the accounts endpoint to create new subaccounts in your account. Subaccounts are created as child accounts of the account specified in the "account" field in the body of the request.

    curl POST example that creates a new subaccount named "Nested_Subaccount" in the account specified in the account field.

      curl -d '{"account" : "https://www.cradlepointecm.com/api/v2/accounts/<account number>/", "name" : "Nested_Subaccount"}' -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
      

    Response body for curl POST example

      {
       "account" : "https://www.cradlepointecm.com/api/v2/accounts/308/",
       "is_disabled" : false,
       "name" : "Nested_Subaccount",
       "id" : "84954",
       "resource_url" : "https://www.cradlepointecm.com/api/v2/accounts/"
    }
      
  • PUT Examples
  • Use PUT requests to the accounts endpoint to modify subaccounts in your account. Payloads to the PUT method for the accounts endpoint can modify the name field.

    curl PUT request example

    curl -v -X PUT -H "X-ECM-API-ID:40961453-652c-48bc-8445-2cfeb36d2c4a" -H "X-ECM-API-KEY:d02aacae1b4b77967014b7270812e8a465ac3174" -H "X-CP-API-ID:a939a410" -H "X-CP-API-KEY:808163e5193491974cd55eda5120ed9d" -H "Content-Type:application/json" "https://www.cradlepointecm.com/api/v2/accounts/36304/" -d '{"name": "New Subaccount Name"}' 
      

    Response body for curl POST example

    {"account": "https://www.cradlepointecm.com/api/v2/accounts/<account number>/", 
     "id": "<id>", 
     "is_disabled": false, 
     "name": "New Subaccount Name", 
     "resource_url": "https://www.cradlepointecm.com/api/v2/accounts/<id>/"}
      
  • DELETE Example
  • Use DELETE requests to the accounts endpoint to delete subaccounts in your account. DELETE requests require the ID of the subaccount to delete, passed in the path of the URL. If a subaccount contains users, they must be removed from the subaccount before the DELETE action can proceed.

    curl DELETE example

    curl -v -X DELETE -H "X-ECM-API-ID:40961453-652c-48bc-8445-2cfeb36d2c4a" -H "X-ECM-API-KEY:d02aacae1b4b77967014b7270812e8a465ac3174" -H "X-CP-API-ID:a939a410" -H "X-CP-API-KEY:808163e5193491974cd55eda5120ed9d" "https://www.cradlepointecm.com/api/v2/accounts/36304/" 
      

    Successful DELETE action return a 204 response code with no response body with no content.

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.

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

    It is important to note that certain activities that are visible in the NCM Activity Logs are not available when calling this endpoint. These activities include the following:

    • Changes to account level settings including Session Length, Forced MFA, Enhanced Login Security, and Company Contacts
    • Creation/deletion and updates of user authorization within a company
    • Creation/deletion and updates of users
    • User logins and logouts
  • Activity Logs Endpoint Fields and Filters
  • This table lists the fields associated with the activity_logs endpoint. Fields with operators specified in the Filter column indicate that those fields can be used as filters.

    Supported methods: GET

    The Activity Logs Object

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

    Endpoint base path:

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

    IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
    Correct format:    https://www.cradlepointecm.com/api/v2/<endpoint name>/
    Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
    Note: * indicates the attribute is required in the request body for PUT and POST requests.
    Note: ! indicates the attribute is required for PUT request
  • Tips for Using the NetCloud API
  • When making API calls with curl in a console session, it can be helpful to define variables for your API keys, payloads, and the base URL of the endpoint for re-use with each curl statement.
    Please note that the method for setting variables in your console of choice can vary depending on the console/OS used. These variable definition examples are BASH specific; other console tools can require slightly different syntax to define these variables in a console session.

    • X_ECM_API_ID="<X-ECM-API-ID>"
    • X_ECM_API_KEY="<X-ECM-API-KEY>"
    • X_CP_API_ID="<X-CP-API-ID>"
    • X_CP_API_KEY="<X-CP-API-KEY>"
    • -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY"
    • URL="https://www.cradlepointecm.com/api/v2/activity_logs/"
    • BODY = -d '{"<field name>": "<field value>"}

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

  • GET Examples
  • Example curl GET request/response to the activity_logs endpoint without filters applied. This retrieves all the Activity Log records in the account.

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/activity_logs/?account=<account number>"   

    Response body for curl GET example without filters applied.

    {
        "data": [
            {
                "action": {
                    "after": {
                        "account": {
                            "id": "8432354",
                            "name": "API-created-subaccount"
                        }
                    },
                    "before": {
                        "account": {
                            "id": "36304",
                            "name": "New Subaccount Name"
                        }
                    },
                    "id": "ceac0376-675c-11eb-bf0a-56fa34ed58df3",
                    "timestamp": "2021-02-05T02:49:46.696383Z",
                    "type": 3,
                    "type_name": "update"
                },
                "actor": {
                    "email": "actor@email.address",
                    "id": "045fgBd0s344tzah0g",
                    "type": 5,
                    "type_name": "sso_user"
                },
                "object": {
                    "id": "119012951",
                    "role": {
                        "id": "4",
                        "name": "account_read_only"
                    },
                    "type": 12,
                    "type_name": "authorization",
                    "user": {
                        "email": "user@email.address",
                        "id": "vOAwbBPFbagt12l9"
                    }
                }
            }
        ],
        "meta": {
            "limit": 20,
            "next": "https://www.cradlepointecm.com/api/v2/activity_logs/?action__id__lt=8f9db4d2-6a5d-11eb-a58d-5269e9f352ab"
        }
    }   
                

    Example curl GET request/response to the activity_logs endpoint with the created_at__exact filter applied. This retrieves the Activity Log action record with the matching timestamp.

    curl -v -X GET curl -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY"  "https://www.cradlepointecm.com/api/v2/activity_logs/?created_at__exact=2021-02-05T02%3A49%3A46.696383Z"     
         

    Example response:

    {
        "data": [
            {
                "action": {
                    "after": {
                        "account": {
                            "id": "8432354",
                            "name": "API-created-subaccount"
                        }
                    },
                    "before": {
                        "account": {
                            "id": "36304",
                            "name": "New Subaccount Name"
                        }
                    },
                    "id": "ceac0376-675c-11eb-bf0a-56fa34ed58df3",
                    "timestamp": "2021-02-05T02:49:46.696383Z",
                    "type": 3,
                    "type_name": "update"
                },
                "actor": {
                    "email": "actor@email.address",
                    "id": "045fgBd0s344tzah0g",
                    "type": 5,
                    "type_name": "sso_user"
                },
                "object": {
                    "id": "119012951",
                    "role": {
                        "id": "4",
                        "name": "account_read_only"
                    },
                    "type": 12,
                    "type_name": "authorization",
                    "user": {
                        "email": "user@email.address",
                        "id": "vOAwbBPFbagt12l9"
                    }
                }
            }
        ],
        "meta": {
            "limit": 20,
            "next": "https://www.cradlepointecm.com/api/v2/activity_logs/?action__id__lt=8f9db4d2-6a5d-11eb-a58d-5269e9f352ab"
        }
    }           
                

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.

Supported methods: GET, POST, PATCH, DELETE
  • alert_push_destinations Endpoint Fields and Filters
  • This table lists the fields associated with the alert_push_destinations endpoint. Fields with operators specified in the Filter column indicate that those fields can be used as filters.

    Parameter Data Type Filter Sort Expand Description Permissions
    account url The URL of the user's account that created the alert_push_destination record. Read Only
    authentication JSON See the Field Notes section below for details. Read/Write
    destination_config_id* timeuuid =, in, gt, lt=, __in, __isnull Unique ID of an Alert Push Destination. A timeuuid type. Read Only
    enabled boolean Indicates whether this configuration is enabled. Defaults to true. Read/Write
    endpoint JSON See the Field Notes section below for details. Read/Write
    last_error_at timestamp Timestamp last_error_text was produced. Read Only
    last_error_text string If this configuration has generated any push errors, this is the text of the last error. Read Only
    name string =, __in, __gt, __gte, __lt, __lte Friendly name for destination. Read/Write
    suspended boolean Indicates whether a destination is suspended. See the Field Notes section below for details. Read/Write
    updated_at timestamp Last time this alert_push_destinations record was updated. Read only, generated by server. Read Only
    Note: * indicates the attribute is required for PATCH and DELETE requests.

    Endpoint base path:

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

    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>
  • Tips for Using the NetCloud API
  • When making API calls with curl in a console session, it can be helpful to define variables for your API keys, payloads, and the base URL of the endpoint for re-use with each curl statement.
    Please note that the method for setting variables in your console of choice can vary depending on the console/OS used. These variable definition examples are BASH specific; other console tools can require slightly different syntax to define these variables in a console session.

    • X_ECM_API_ID="<X-ECM-API-ID>"
    • X_ECM_API_KEY="<X-ECM-API-KEY>"
    • X_CP_API_ID="<X-CP-API-ID>"
    • X_CP_API_KEY="<X-CP-API-KEY>"
    • -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY"
    • URL="https://www.cradlepointecm.com/api/v2/alert_push_destinations/"
    • BODY = -d '{"<field name>": "<field value>"}

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

  • Field Notes
  • Endpoint field

    The endpoint field is a flat JSON dictionary. It supports only a single key, “url”. The url field is a string containing the push destination URL. This field is required for POST and may be updated with PATCH. For example: {“url“: “https://pushdestinationserver.somecustomer.com”}

    Note: You are not allowed to save two different push configurations for your account that both have the same endpoint URL. An error is thrown on POST/PATCH if this is attempted.

    Authentication field

    The authentication field is a flat JSON dictionary. It supports only a single key, “secret”. TThe authentication field is an arbitrary string containing a shared secret, such as a UUID. This field is required for POST and may be updated with PATCH. On GET, the value will always be returned as “*” for security. For example:

    POST or PATCH:
    {“secret“: “thisIsAUniqueValueNoOneWillBeAble2Guess”}

    GET:
    {“secret“: “*”} A SHA256 hash of this secret + the body is sent in the “X-CP-Signature” HTTP header of each pushed alert message. This allows the customer to authenticate the source of the push message.

    Customers authenticate the source of the push message using webhooks on their destination server. Webhooks are an increasingly popular method for communication between applications. The following pattern is a Python webhook example for authentication of a push message's secret.

    Note: The following webhook code is for example purposes only and isn't intended for production use. It is designed to provide a general approach to follow in your language of choice. See the Sample Code page (link in the menu on the left) for detailed information on webhooks and using the NetCloud Alert Push API.

        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
            }
        

    Suspended field

    The suspended field in the alert_push_destinations endpoint represents the current connectivity state of a push destination defined in the endpoint field. The value of the suspended field can be either “True” indicating the push destination endpoint is suspended, or “False” indicating that the push destination endpoint is not suspended. The suspended field’s value can be patched from “True” to “False” {“suspended”: “False”}. Since the push destination might have become reachable after the suspended field was set to “True”, patching {“suspended”: “False”} allows you to try to reach it again.

    Note: The suspended field can’t be patched from “False” to “True.”

  • GET Examples
  • To get all the Alert Push Destinations configured in your account:

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/alert_push_destinations/"
    

    To retrieve a single Alert Push Destination, pass the destination_config_id as a query param in the URL.

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/alert_push_destinations/?destination_config_id=4d75218a-665a-11eb-9aa9-42edcb7bf284"
    

    Example response body of a GET request for a single alert_push_notification record.

    {
        "data": [
            {
                "account": "https://www.cradlepointecm.com/api/v2/accounts/<account number>/",
                "authentication": {
                    "secret": "*"
                },
                "consecutive_error_count": 0,
                "destination_config_id": "4d75218a-665a-11eb-9aa9-42edcb7bf284",
                "enabled": true,
                "endpoint": {
                    "url": "https://example.com.com"
                },
                "health": "active",
                "last_error_at": null,
                "last_error_text": null,
                "name": "mypushexample",
                "retry_count": 0,
                "total_error_count": 0,
                "updated_at": "2021-02-03T19:59:19.754418%2B00:00"
            }
        ],
        "meta": {
            "limit": 20,
            "next": null
        }
    }
    
  • POST Examples
  • POST example for creating a new Alert Push Destination that uses "https://example.com.com" as its destination.

    Note: The invalid example url "https://example.com.com" is corrected in the PATCH example in the next section.

    curl -v -X POST -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" -H "Content-Type:application/json" "https://www.cradlepointecm.com/api/v2/alert_push_destinations/" -d '{
    "endpoint": {"url": "https://example.com.com"},
    "authentication": {"secret": "mysecretsecret"},
    "name": "mypushexample"
    }'
    

    Example response body

    {
        "account": "https://www.cradlepointecm.com/api/v2/accounts/<account number>/",
        "authentication": {
            "secret": "*"
        },
        "consecutive_error_count": 0,
        "destination_config_id": "4d75218a-665a-11eb-9aa9-42edcb7bf284",
        "enabled": true,
        "endpoint": {
            "url": "https://example.com.com"
        },
        "health": "active",
        "last_error_at": null,
        "last_error_text": null,
        "name": "mypushexample",
        "resource_url": "https://www.cradlepointecm.com/api/v2/alert_push_destinations/",
        "retry_count": 0,
        "total_error_count": 0,
        "updated_at": "2021-02-03T19:59:19.754418%2B00:00"
    }
    
  • PATCH Examples
  • The following example updates the url field in an Alert Push Destination.

    curl -v -X PATCH -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" -H "Content-Type:application/json" "https://www.cradlepointecm.com/api/v2/alert_push_destinations/1cf2c024-64e5-11eb-be7d-42edcb7bf284/" -d '{"url": "https://example.com"}'
    

    Successful PATCH requests return an empty response body with a 201 response code.

  • DELETE Example
  • To delete an Alert Push Notification, call the alert_push_notifications endpoint and pass the destination_config_id of the Alert Push Notification to delete.

    curl -v -X DELETE -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/alert_push_destinations/1cf2c024-64e5-11eb-be7d-42edcb7bf284/"
    

    Successful DELETE requests return an empty response body with a 204 response code.

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.

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.

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.

Supported methods: GET, POST, PATCH, DELETE.
  • alert_rules Endpoint Fields and Filters
  • This table lists the fields associated with the alert_rules endpoint. Fields with operators specified in the Filter column indicate that those fields can be used as filters.

    Parameter Data Type Filter Sort Expand Description Permissions
    account url Account of user who created the Alert Rule Read Only
    alert_config_id url {=, in, gt, lt} Unique ID of an Alert Rule. A timeuuid type. Read Only
    associated_accounts List of ints List of ints that identify accounts to include alert types from. These become part of your Alert Rule. Read/Write
    associated_groups List of ints List of ints that identify groups to include alert types from. These become part of your Alert Rule. Read/Write
    email_destinations List of ints Use this to list email destinations to receive notification when this alert type is triggered. This is a list of user IDs; NetCloud converts these to email addresses. To obtain user IDs for this field, call the "users" endpoint. Read/Write
    filter_criteria Dictionary with two keys: alert_type__in and external_id__in. Use a dictionary to specify alert types by name for your Alert Rule. You can use any alert-type name available in NetCloud. Read/Write
    http_destinations list(timeuuid) Use this to list HTTP destinations to receive notification when this alert type is triggered. This is a list destination_config_ids (timeuuids) that link Alert Rules with alert_push_destinations records. Read/write
    schedule timestamp Schedule for sending notifications. Can be Immediately|Hourly|Daily. Read/Write
    settings json Additional settings for particular alert types. Currently suports extra information only for PDP service-overage alerts. Read/write
    updated_at timestamp Last date/time an alert_rules record was updated. Read only

    Endpoint base path:

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

    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>
  • Tips for Using the NetCloud API
  • When making API calls with curl in a console session, it can be helpful to define variables for your API keys, payloads, and the base URL of the endpoint for re-use with each curl statement.
    Please note that the method for setting variables in your console of choice can vary depending on the console/OS used. These variable definition examples are BASH specific; other console tools can require slightly different syntax to define these variables in a console session.

    • X_ECM_API_ID="<X-ECM-API-ID>"
    • X_ECM_API_KEY="<X-ECM-API-KEY>"
    • X_CP_API_ID="<X-CP-API-ID>"
    • X_CP_API_KEY="<X-CP-API-KEY>"
    • -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY"
    • URL="https://www.cradlepointecm.com/api/v2/alert_rules/"
    • BODY = -d '{"<field name>": "<field value>"}

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

  • GET Examples
  • To get all the Alert Rules configured in your account:

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/alert_rules/"
    

    To retrieve a single Alert Rule, pass the alert_config_id as a query param in the URL.

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/alert_rules/?alert_config_id=1a5faaf8-6649-11eb-9823-42edcb7bf284"

    Example response body of a GET request for a single alert_rule record.

    {
        "data": [
            {
                "account": "https://www.cradlepointecm.com/api/v2/accounts/<account number>/",
                "alert_config_id": "1a5faaf8-6649-11eb-9823-42edcb7bf284",
                "associated_accounts": [],
                "associated_groups": [],
                "email_destinations": [],
                "external_rules": null,
                "filter_criteria": {
                    "alert_type__in": [
                        "account_locked"
                    ]
                },
                "http_destinations": [
                    "1cf2c024-64e5-11eb-be7d-42edcb7bf284"
                ],
                "last_summary_ts": null,
                "schedule": "daily",
                "settings": null,
                "updated_at": "2021-02-03T17:56:12.605494+00:00"
            }
        ],
        "meta": {
            "limit": 20,
            "next": null
        }
    }     
    

     

  • POST Examples
  • Example POST request to add an Alert Rule for an account_locked alert type that registers an alert daily and sends push notifications to a single HTTP destination. A Content-Type header set to "application/json" must be included in the request.

    curl -v -X POST -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" -H "Content-Type:application/json" "https://www.cradlepointecm.com/api/v2/alert_rules/" -d '{
            "schedule": "daily",
            "filter_criteria": {
              "alert_type__in": ["account_locked"]
            },
            "http_destinations": ["1cf2c024-64e5-11eb-be7d-42edcb7bf284"]
          }'
          

    Example response body.

    {
        "account": "https://www.cradlepointecm.com/api/v2/accounts/<account number>/",
        "alert_config_id": "1a5faaf8-6649-11eb-9823-42edcb7bf284",
        "associated_accounts": [],
        "associated_groups": [],
        "email_destinations": [],
        "external_rules": null,
        "filter_criteria": {
            "alert_type__in": [
                "account_locked"
            ]
        },
        "http_destinations": [
            "1cf2c024-64e5-11eb-be7d-42edcb7bf284"
        ],
        "last_summary_ts": null,
        "resource_url": "https://www.cradlepointecm.com/api/v2/alert_rules/",
        "schedule": "daily",
        "settings": null,
        "updated_at": "2021-02-03T17:56:12.605494+00:00"
    }
               

    If you use filter_criteria in an Alert Rule that contains pdp_router_overage or pdp_account_overage types, you must supply entries for them in the settings field using the following pattern.

     
    {
        "settings": {
            "pdp_router_overage": {
                "carrier": "VERIZON",
                "thresholds": [
                    25,
                    50,
                    75,
                    90
                ]
            },
            "pdp_account_overage": {
                "carrier": "VERIZON",
                "thresholds": [
                    50,
                    60,
                    80
                ]
            }
        }
    }
               

    The settings contain a key for each PDP type that is present in the filter_criteria field. Any settings for types not in the filters field, or non-PDP types, are ignored. Each alert type key contains a dictionary with two keys:

    • “carrier”: This contains the name of a carrier as it appears in your carrier data (e.g., VERIZON, SPRINT). This should be a carrier for which the server has a matching data plan already configured for this account, on the Carrier dashboard in NCM. The server will use this carrier name to find a matching PDP data plan which the alert will be attached. If there is no existing data plan for this carrier/account combination, an error is thrown on save validation.
    • “thresholds”: This contains a list of integers representing the percent thresholds at which an alert is triggered. For example, “Verizon data usage alerted at 80% of monthly limit”.
  • PATCH Examples
  • To update an Alert Rule with a PATCH request, call the alert_rules endpoint with the alert_config_id of the Alert Rule to update in the URL. A Content-Type header set to "application/json" must be included in the request.

    The following example updates the schedule field in an Alert Rule.

    curl -v -X PATCH -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" -H "Content-Type:application/json" "https://www.cradlepointecm.com/api/v2/alert_rules/8696b080-1dea-11b2-bfff-ffffffffffff/" -d '{
          "schedule": "hourly"
          }   
          

    Successful PATCH requests return an empty response body with a 201 response code.

     

  • DELETE Example
  • To delete an Alert Rule, call the alert_rules endpoint and pass the alert_config_id of the Alert Rule to delete.

    curl -v -X DELETE -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/alert_rules/94026980-1def-11b2-bfff-ffffffffffff/"
        

    Successful DELETE requests return an empty response body with a 204 response code.

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.

Special Notes:

  • This endpoint does not have the standard filter limits of 100 values per field (ex. router__in=[1234,4321,...])
  • This endpoint will have only one value out of the router field and the account field. The other value will always be "null." You can filter on the value being null or not with the isnull operation. For example, "/alerts/?router__isnull=true" will give you alerts where the router field has a "null" value.
  • See the "router_alerts" endpoint on this page for details on alerts specific to routers.
Supported methods: GET.
  • alerts Endpoint Fields and Filters
  • This table lists the fields associated with the alerts endpoint. Fields with operators specified in the Filter column indicate that those fields can be used as filters.

    Parameter Data Type Filter Sort Expand Description
    account url =, __in, __isnull Account this alert is related to, or null if the router field has a value
    created_at timestamp __gt, __lt Time the alert record was created in NCM
    created_at_timeuuid timeuuid =, __in, __gt, __gte, __lt, __lte A unique ID associated with the created_at timestamp. Ordering by the ID is equivalent to time ordering. This field can identify a specific record or be used for paging.
    detected_at timestamp Time the alert was detected
    friendly_info string Human-readable description of the alert
    info json Alert-type specific information
    router url =, __in, __isnull Device this alert is related to, or null if the account field has a value
    type string =, __in The type of the alert

    Endpoint base path:

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

    IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
    Correct format:    https://www.cradlepointecm.com/api/v2/<endpoint name>/
    Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
  • Tips for Using the NetCloud API
  • When making API calls with curl in a console session, it can be helpful to define variables for your API keys, payloads, and the base URL of the endpoint for re-use with each curl statement.
    Please note that the method for setting variables in your console of choice can vary depending on the console/OS used. These variable definition examples are BASH specific; other console tools can require slightly different syntax to define these variables in a console session.

    • X_ECM_API_ID="<X-ECM-API-ID>"
    • X_ECM_API_KEY="<X-ECM-API-KEY>"
    • X_CP_API_ID="<X-CP-API-ID>"
    • X_CP_API_KEY="<X-CP-API-KEY>"
    • -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY"
    • URL="https://www.cradlepointecm.com/api/v2/alerts/"
    • BODY = -d '{"<field name>": "<field value>"}

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

  • GET Examples
  • Example curl GET request/response to the alerts endpoint without filters applied.

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" -H "Content-Type:application/json" "https://www.cradlepointecm.com/api/v2/alerts/"

    Response body for curl GET example

    Note: The account field is null if the router field contains a value.

    {
        "data": [
            {
                "account": null,
                "created_at": "2020-12-07T17:44:19.430235+00:00",
                "created_at_timeuuid": "d554418c-38b3-11eb-acd7-32b969db3e3f",
                "detected_at": "2020-12-07T17:44:18+00:00",
                "friendly_info": "User admin has logged into the router from 127.0.0.1.",
                "info": {
                    "ip": "127.0.0.1",
                    "time": [
                        "2020-12-07 17:44:18",
                        "UTC"
                    ],
                    "type": "login_success",
                    "user": "admin"
                },
                "router": "https://www.cradlepointecm.com/api/v2/routers/2162719/",
                "type": "login_success"
            },
            {
                "account": null,
                "created_at": "2020-12-04T09:20:30.538148+00:00",
                "created_at_timeuuid": "f4442066-3611-11eb-bd86-5ebca3547463",
                "detected_at": "2020-12-04T09:16:16+00:00",
                "friendly_info": "The ethernet port \"Ethernet\" has connected to the network.",
                "info": {
                    "alert_type": "ethernet_wan_connected",
                    "history": [],
                    "info": {
                        "mac": "00:30:44:47:cb:09",
                        "port": "Ethernet",
                        "raw_port": "eth0",
                        "reason": "Manual",
                        "type": "ethernet",
                        "uid": "wan"
                    },
                    "status": "connected",
                    "time": [
                        "2020-12-04 09:16:16",
                        "UTC"
                    ],
                    "type": "wan_status_change"
                },
                "router": "https://www.cradlepointecm.com/api/v2/routers/2162719/",
                "type": "ethernet_wan_connected"
            },
            ... 
            ],
            "meta": {
                "limit": 20,
                "next": "https://www.cradlepointecm.com/api/v2/alerts/?created_at_timeuuid__lt=f4778d8a-3243-11eb-bce8-522895cf33a7"
            }
        }
     

    Example curl GET request/response to the alerts endpoint with a filters applied for the type field with a value ethernet_wan_connected.

    curl -v -X GET -H "X-ECM-API-ID:40961453-652c-48bc-8445-2cfeb36d2c4a" -H "X-ECM-API-KEY:d02aacae1b4b77967014b7270812e8a465ac3174" -H "X-CP-API-ID:a939a410" -H "X-CP-API-KEY:808163e5193491974cd55eda5120ed9d" -H "Content-Type:application/json" "https://www.cradlepointecm.com/api/v2/alerts/?type=ethernet_wan_connected"

    Response body for curl GET example

    {
        "data": [
            {
                "account": null,
                "created_at": "2020-12-04T09:20:30.538148+00:00",
                "created_at_timeuuid": "f4442066-3611-11eb-bd86-5ebca3547463",
                "detected_at": "2020-12-04T09:16:16+00:00",
                "friendly_info": "The ethernet port \"Ethernet\" has connected to the network.",
                "info": {
                    "alert_type": "ethernet_wan_connected",
                    "history": [],
                    "info": {
                        "mac": "00:30:44:47:cb:09",
                        "port": "Ethernet",
                        "raw_port": "eth0",
                        "reason": "Manual",
                        "type": "ethernet",
                        "uid": "wan"
                    },
                    "status": "connected",
                    "time": [
                        "2020-12-04 09:16:16",
                        "UTC"
                    ],
                    "type": "wan_status_change"
                },
                "router": "https://www.cradlepointecm.com/api/v2/routers/2162719/",
                "type": "ethernet_wan_connected"
            },
            {
                "account": null,
                "created_at": "2020-11-29T13:08:21.165839+00:00",
                "created_at_timeuuid": "f4879e94-3243-11eb-a03e-522895cf33a7",
                "detected_at": "2020-11-29T13:06:11+00:00",
                "friendly_info": "The ethernet port \"Ethernet\" has connected to the network.",
                "info": {
                    "alert_type": "ethernet_wan_connected",
                    "history": [],
                    "info": {
                        "mac": "00:30:44:47:cb:09",
                        "port": "Ethernet",
                        "raw_port": "eth0",
                        "reason": "Manual",
                        "type": "ethernet",
                        "uid": "wan"
                    },
                    "status": "connected",
                    "time": [
                        "2020-11-29 13:06:11",
                        "UTC"
                    ],
                    "type": "wan_status_change"
                },
                "router": "https://www.cradlepointecm.com/api/v2/routers/2162719/",
                "type": "ethernet_wan_connected"
            },
            {
                "account": null,
                "created_at": "2020-11-29T13:08:21.105197+00:00",
                "created_at_timeuuid": "f47e5dc2-3243-11eb-b40d-522895cf33a7",
                "detected_at": "2020-11-29T13:04:56+00:00",
                "friendly_info": "The ethernet port \"Ethernet\" has connected to the network.",
                "info": {
                    "alert_type": "ethernet_wan_connected",
                    "history": [],
                    "info": {
                        "mac": "00:30:44:47:cb:09",
                        "port": "Ethernet",
                        "raw_port": "eth0",
                        "reason": "Manual",
                        "type": "ethernet",
                        "uid": "wan"
                    },
                    "status": "connected",
                    "time": [
                        "2020-11-29 13:04:56",
                        "UTC"
                    ],
                    "type": "wan_status_change"
                },
                "router": "https://www.cradlepointecm.com/api/v2/routers/2162719/",
                "type": "ethernet_wan_connected"
            },
    ...
        ],
        "meta": {
            "limit": 20,
            "next": null
        }
    }

    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: creates an alert when the remaining battery life reaches 62%
  • Battery Over Current: creates an alert when the battery's current reaches 3.2 amps
  • Battery Over Temperature: creates an alert when the battery's temperature reaches 50 degrees Celsius
  • Battery Over Voltage: creates an alert when the battery's recommended voltage reaches 8.5V (8500 mV)
  • Battery System Low Power: creates an alert when the battery's power reaches 20% charge
  • Battery System Power Off: creates an alert when the battery's power reaches 7% charge
Supported methods: GET.
  • batteries Endpoint Fields and Filters
  • This table lists the fields associated with the batteries endpoint. Fields with operators specified in the Filter column indicate that those fields can be used as filters.

    Parameter Data Type Filter Sort Expand Description
    type string Type of power source
    router_id int =, __in ID of the router containing the battery(s) to query
    created_at timestamp Date/time of battery's initial record in NetCloud
    updated_at timestamp Battery's most recent update date/time in NetCloud
    serial string Battery serial number
    milliamps int Battery current (milliamps, negative indicates discharging)
    millivolts int Battery voltage (millivolts)
    temp int Battery temperature
    rsoc int Relative state of charge
    health int Ratio of present capacity and design capacity
    time_remaining int Battery time remaining, in minutes
    manufacturer string Manufacturer of battery
    status string State of battery (charging, discharging, idle)

    Endpoint base path:

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

    IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
    Correct format:    https://www.cradlepointecm.com/api/v2/<endpoint name>/
    Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
  • Tips for Using the NetCloud API
  • When making API calls with curl in a console session, it can be helpful to define variables for your API keys, payloads, and the base URL of the endpoint for re-use with each curl statement.
    Please note that the method for setting variables in your console of choice can vary depending on the console/OS used. These variable definition examples are BASH specific; other console tools can require slightly different syntax to define these variables in a console session.

    • X_ECM_API_ID="<X-ECM-API-ID>"
    • X_ECM_API_KEY="<X-ECM-API-KEY>"
    • X_CP_API_ID="<X-CP-API-ID>"
    • X_CP_API_KEY="<X-CP-API-KEY>"
    • -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY"
    • URL="https://www.cradlepointecm.com/api/v2/batteries/"
    • BODY = -d '{"<field name>": "<field value>"}

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

  • GET Examples
  • Example curl GET request/response to the batteries endpoint with the required router_id filter applied.

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY"  "https://www.cradlepointecm.com/api/v2/batteries/?router.id=15496"

    Response body for curl GET example

    {
        "data": [
             {
                "type": "battery",
                "id": "15496",
                "created_at": "2020-01-01 00:00:00"
                "updated_at": "2020-01-02 00:00:00"
                "serial": "12345",
                "milliamps": -257,
                "health": 100,
                "rsoc": 62,
                "temp": 29,
                "time_remaining": 1131,
                "millivolts": 7567,
                "manufacturer": "GETAC",
                "status": "Discharging",
            },
            {
                "type": "battery",
                "id": "15496",
                "created_at": "2020-01-01 00:00:00"
                "updated_at": "2020-01-02 00:00:00"
                "serial": "45345",
                "milliamps": -221,
                "health": 100,
                "rsoc": 59,
                "temp": 27,
                "time_remaining": 1061,
                "millivolts": 7545,
                "manufacturer": "GETAC",
                "status": "Idle",
            },
            {
                ...
            }
        ],
        }
    }
     

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.

Supported methods: GET, PUT, PATCH.
  • configuration_managers Endpoint Fields and Filters
  • This table lists the fields associated with the configuration_managers endpoint. Fields with operators specified in the Filter column indicate that those fields can be used as filters.

    Parameter Data Type Filter Sort Expand Description Permissions
    account url =, __in Account that owns the configuration object Read Only
    router url =, __in The router the configuration_managers record belongs to Read Only
    id* int =, __in The ID of a configuration_managers record Read Only
    suspended boolean = The suspended state of a configuration Read/Write
    synched boolean = The synched state of a configuration Read Only
    version_number int =, __gt, __lt The version number of a configuration Read Only
    Note: * indicates the attribute is required for PUT and PATCH requests.

    Endpoint base path:

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

    IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
    Correct format:    https://www.cradlepointecm.com/api/v2/<endpoint name>/
    Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
  • Tips for Using the NetCloud API
  • When making API calls with curl in a console session, it can be helpful to define variables for your API keys, payloads, and the base URL of the endpoint for re-use with each curl statement.
    Please note that the method for setting variables in your console of choice can vary depending on the console/OS used. These variable definition examples are BASH specific; other console tools can require slightly different syntax to define these variables in a console session.

    • X_ECM_API_ID="<X-ECM-API-ID>"
    • X_ECM_API_KEY="<X-ECM-API-KEY>"
    • X_CP_API_ID="<X-CP-API-ID>"
    • X_CP_API_KEY="<X-CP-API-KEY>"
    • -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY"
    • URL="https://www.cradlepointecm.com/api/v2/configuration_managers/"
    • BODY = -d '{"<field name>": "<field value>"}

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

  • GET Examples
  • Example curl GET request/response to the configuration_managers endpoint without filters applied.

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/configuration_managers/"

    Response body excerpt for curl GET example. This is only a portion of a configuration_managers record.

    {
        "data": [
            {
                "account": "https://www.cradlepointecm.com/api/v2/accounts/<account number>/",
                "actual": [
                    {
                        "ecm": {
                            "config_version": 20
                        },
                        "gre": {
                            "tunnels": {
                                "0": {
                                    "_id_": "00000000-e18b-3714-86cd-152498cbeeec",
                                    "dhcp_enabled": false,
                                    "enabled": true,
                                    "exception_route_mode": "route",
                                    "fail_back_to": "",
                                    "fail_over_to": "",
                                    "keep_alive_enabled": true,
                                    "keep_alive_period": 10,
                                    "keep_alive_retries": 3,
                                    "key": null,
                                    "local_network": "10.0.0.1",
                                    "name": "GRE Tunnel",
                                    "nemo": false,
                                    "netmask": "255.255.255.252",
                                    "remote_gateway": "166.18.88.35",
                                    "remote_network": "10.0.0.2",
                                    "routes": [
                                        {}
                                    ],
                                    "ttl": 64,
                                    "wan_dev": "disabled",
                                    "wan_trigger_field": "uid",
                                    "wan_trigger_predicate": "is",
                                    "wan_trigger_value": ""
                                }
                            }
                        },
                        ... 
                    }
                ]
            }
        ]                
     
  • PUT Examples
  • Example curl PUT request/response to the configuration_managers endpoint to clear a configuration object. Please note that the configuration object in a configuration_managers record can be modified. The target, actual, and pending objects in a configuration_managers record are read only.

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

    Response body for curl PUT example

    202 Accepted
            {
                 "configuration": [{}, []]
             }
  • PATCH Examples
  • Example curl PATCH request/response to the configuration_managers endpoint. This updates the client_usage boolean field to false.

    curl -v -X PATCH -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" -H "Content-Type:application/json" "https://www.cradlepointecm.com/api/v2/configuration_managers/2163609/" -d '{    
    "configuration": [
            {
                "stats": {
                    "client_usage": {
                        "enabled": false
                    }
                }
            },
            []
        ]
    }'

    The example response body for curl PATCH actions to the configuration_managers endpoint returns the updated configuration.

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

Supported methods: GET, POST, DELETE.

The Device App Binding Object

Parameter Data Type Filter Sort Expand Description Permissions
account* url =, __in Account that owns the object Read/Write
app_version* url =, __in The app version that will be tied to the group binding Read/Write
created_at timestamp Time the device app object was created Read Only
group* url =, __in The group in which the binding will be applied Read/Write
id int =, __in Object ID Read Only
resource_url url Object URL Read/Write
state string =, __in State of the device app Read/Write
updated_at timestamp Time of last attribute update Read/Write
Note:* indicates the attribute is required for PUT and POST requests.

Endpoint base path:

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

IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
Correct format:    https://www.cradlepointecm.com/api/v2/<endpoint name>/
Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
{
 {
    "data": [
        {
            "account": "https://www.cradlepointecm.com/api/v2/accounts/241/",
            "app_version": "https://www.cradlepointecm.com/api/v2/device_app_versions/112/",
            "group": "https://www.cradlepointecm.com/api/v2/groups/93/",
            "state": "running",
            "created_at": "2015-08-10T16:19:31.784055+00:00",
            "updated_at": "2015-09-22T10:35:55.182602+00:00"
            "id": "17",
            "resource_url": "https://www.cradlepointecm.com/api/v2/device_apps/17/",
        },
        { ... }
    ],
    "meta": {
        "limit": 20,
        "next": null,
        "offset": 0,
        "previous": null
    }
}

Device App Bindings Methods

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

Supported methods: GET.
  • device_app_states Endpoint Fields and Filters
  • This table lists the fields associated with the device_app_states endpoint. Fields with operators specified in the Filter column indicate that those fields can be used as filters.

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

    Endpoint base path:

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

    IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
    Correct format:    https://www.cradlepointecm.com/api/v2/<endpoint name>/
    Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
  • Tips for Using the NetCloud API
  • When making API calls with curl in a console session, it can be helpful to define variables for your API keys, payloads, and the base URL of the endpoint for re-use with each curl statement.
    Please note that the method for setting variables in your console of choice can vary depending on the console/OS used. These variable definition examples are BASH specific; other console tools can require slightly different syntax to define these variables in a console session.

    • X_ECM_API_ID="<X-ECM-API-ID>"
    • X_ECM_API_KEY="<X-ECM-API-KEY>"
    • X_CP_API_ID="<X-CP-API-ID>"
    • X_CP_API_KEY="<X-CP-API-KEY>"
    • -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY"
    • URL="https://www.cradlepointecm.com/api/v2/device_app_states/"
    • BODY = -d '{"<field name>": "<field value>"}

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

  • GET Examples
  • Example curl GET request/response to the device_app_states endpoint with the ID filter applied.

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/device_app_states/?account=241"

    Response body for curl GET example

    {
       {
          "data": [
              {
                  "account": "https://www.cradlepointecm.com/api/v2/accounts/241/",
                  "app_version": "https://www.cradlepointecm.com/api/v2/device_app_versions/112/",
                  "state": "started",
                  "router": "https://www.cradlepointecm.com/api/v2/routers/77/"
                  "created_at": "2015-08-10T16:19:31.784055+00:00",
                  "updated_at": "2015-09-22T10:35:55.182602+00:00"
                  "id": "17",
                  "resource_url": "https://www.cradlepointecm.com/api/v2/device_apps/17/",
              },
              { ... }
          ],
          "meta": {
              "limit": 20,
              "next": null,
              "offset": 0,
              "previous": null
          }
      }
     

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

Supported methods: GET, DELETE.
  • device_app_versions Endpoint Fields and Filters
  • This table lists the fields associated with the device_app_versions endpoint. Fields with operators specified in the Filter column indicate that those fields can be used as filters.

    Parameter Data Type Filter Sort Expand Description
    account url =, __in Account that owns the object
    app url =, __in Associated device app
    created_at timestamp Time the device app object was created
    id* int =, __in Object ID
    resource_url url Object URL
    state string =, __in State of the app version
    state_details string Details of the app version state
    updated_at timestamp Time of last attribute update
    version int Version
    Note: * indicates the attribute is required for DELETE requests.

    Endpoint base path:

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

    IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
    Correct format:    https://www.cradlepointecm.com/api/v2/<endpoint name>/
    Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
  • Tips for Using the NetCloud API
  • When making API calls with curl in a console session, it can be helpful to define variables for your API keys, payloads, and the base URL of the endpoint for re-use with each curl statement.
    Please note that the method for setting variables in your console of choice can vary depending on the console/OS used. These variable definition examples are BASH specific; other console tools can require slightly different syntax to define these variables in a console session.

    • X_ECM_API_ID="<X-ECM-API-ID>"
    • X_ECM_API_KEY="<X-ECM-API-KEY>"
    • X_CP_API_ID="<X-CP-API-ID>"
    • X_CP_API_KEY="<X-CP-API-KEY>"
    • -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY"
    • URL="https://www.cradlepointecm.com/api/v2/device_app_versions/"
    • BODY = -d '{"<field name>": "<field value>"}

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

  • GET Examples
  • Example curl GET request/response to the device_app_versions endpoint without filters applied.

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/device_app_versions/"

    Response body for curl GET example

    {
        "data": [
            {
                "account": "https://www.cradlepointecm.com/api/v2/accounts/<account number>/",
                "app": "https://www.cradlepointecm.com/api/v2/device_apps/1441/",
                "created_at": "2021-02-10T22:00:38.433457+00:00",
                "id": "8612",
                "resource_url": "https://www.cradlepointecm.com/api/v2/device_app_versions/8612/",
                "state": "ready",
                "state_details": "",
                "updated_at": "2021-02-10T22:00:38.771163+00:00",
                "version": "1.0.0"
            },
            {
                "account": "https://www.cradlepointecm.com/api/v2/accounts/<account number>/",
                "app": "https://www.cradlepointecm.com/api/v2/device_apps/1442/",
                "created_at": "2021-02-10T22:44:22.763337+00:00",
                "id": "8613",
                "resource_url": "https://www.cradlepointecm.com/api/v2/device_app_versions/8613/",
                "state": "ready",
                "state_details": "",
                "updated_at": "2021-02-10T22:44:23.073839+00:00",
                "version": "2.0.0"
            },
            {
                "account": "https://www.cradlepointecm.com/api/v2/accounts/<account number>/",
                "app": "https://www.cradlepointecm.com/api/v2/device_apps/1441/",
                "created_at": "2021-02-10T23:31:55.828016+00:00",
                "id": "8615",
                "resource_url": "https://www.cradlepointecm.com/api/v2/device_app_versions/8615/",
                "state": "ready",
                "state_details": "",
                "updated_at": "2021-02-10T23:31:56.085865+00:00",
                "version": "1.5.0"
            }
        ],
        "meta": {
            "limit": 20,
            "next": null,
            "offset": 0,
            "previous": null
        }
    }
     

    Example curl GET request/response to the device_app_versions endpoint with the ID filter applied.

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/device_app_versions/?id=8613"

    Response body for curl GET example

    {
        "data": [
            {
                "account": "https://www.cradlepointecm.com/api/v2/accounts//",
                "app": "https://www.cradlepointecm.com/api/v2/device_apps/1442/",
                "created_at": "2021-02-10T22:44:22.763337+00:00",
                "id": "8613",
                "resource_url": "https://www.cradlepointecm.com/api/v2/device_app_versions/8613/",
                "state": "ready",
                "state_details": "",
                "updated_at": "2021-02-10T22:44:23.073839+00:00",
                "version": "2.0.0"
            }
        ],
        "meta": {
            "limit": 20,
            "next": null,
            "offset": 0,
            "previous": null
        }
    }
  • DELETE Example
  • Example curl DELETE request/response to the device_app_versions endpoint. This deletes the device version matching the ID passed in the route.

    curl -v -X DELETE -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/device_app_versions/8613/"

    Successful DELETE actions return a 204 response with no content in the body.

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 the versions of your installed SDK apps.

Supported methods: GET, DELETE.
  • device_apps Endpoint Fields and Filters
  • This table lists the fields associated with the device_apps endpoint. Fields with operators specified in the Filter column indicate that those fields can be used as filters.

    Parameter Data Type Filter Sort Expand Description
    account url =, __in Account that owns the object
    app url =, __in Associated device app
    created_at timestamp Time the device app object was created
    id* int =, __in Object ID
    resource_url url Object URL
    state string =, __in State of the app version
    state_details string Details of the app version state
    updated_at timestamp Time of last attribute update
    version int Version
    Note: * indicates the attribute is required for DELETE requests.

    Endpoint base path:

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

    IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
    Correct format:    https://www.cradlepointecm.com/api/v2/<endpoint name>/
    Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
  • Tips for Using the NetCloud API
  • When making API calls with curl in a console session, it can be helpful to define variables for your API keys, payloads, and the base URL of the endpoint for re-use with each curl statement.
    Please note that the method for setting variables in your console of choice can vary depending on the console/OS used. These variable definition examples are BASH specific; other console tools can require slightly different syntax to define these variables in a console session.

    • X_ECM_API_ID="<X-ECM-API-ID>"
    • X_ECM_API_KEY="<X-ECM-API-KEY>"
    • X_CP_API_ID="<X-CP-API-ID>"
    • X_CP_API_KEY="<X-CP-API-KEY>"
    • -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY"
    • URL="https://www.cradlepointecm.com/api/v2/device_apps/"
    • BODY = -d '{"<field name>": "<field value>"}

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

  • GET Examples
  • Example curl GET request/response to the device_apps endpoint without filters applied.

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/device_app_versions/"

    Response body for curl GET example

    {
        "data": [
            {
                "account": "https://www.cradlepointecm.com/api/v2/accounts/<account number>/",
                "app": "https://www.cradlepointecm.com/api/v2/device_apps/1441/",
                "created_at": "2021-02-10T22:00:38.433457+00:00",
                "id": "8612",
                "resource_url": "https://www.cradlepointecm.com/api/v2/device_app_versions/8612/",
                "state": "ready",
                "state_details": "",
                "updated_at": "2021-02-10T22:00:38.771163+00:00",
                "version": "1.0.0"
            },
            {
                "account": "https://www.cradlepointecm.com/api/v2/accounts/<account number>/",
                "app": "https://www.cradlepointecm.com/api/v2/device_apps/1442/",
                "created_at": "2021-02-10T22:44:22.763337+00:00",
                "id": "8613",
                "resource_url": "https://www.cradlepointecm.com/api/v2/device_app_versions/8613/",
                "state": "ready",
                "state_details": "",
                "updated_at": "2021-02-10T22:44:23.073839+00:00",
                "version": "2.0.0"
            },
            {
                "account": "https://www.cradlepointecm.com/api/v2/accounts/<account number>/",
                "app": "https://www.cradlepointecm.com/api/v2/device_apps/1441/",
                "created_at": "2021-02-10T23:31:55.828016+00:00",
                "id": "8615",
                "resource_url": "https://www.cradlepointecm.com/api/v2/device_app_versions/8615/",
                "state": "ready",
                "state_details": "",
                "updated_at": "2021-02-10T23:31:56.085865+00:00",
                "version": "1.5.0"
            }
        ],
        "meta": {
            "limit": 20,
            "next": null,
            "offset": 0,
            "previous": null
        }
    }
     

    Example curl GET request/response to the device_apps endpoint with the ID filter applied.

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/device_app_versions/?id=8613"

    Response body for curl GET example

    {
        "data": [
            {
                "account": "https://www.cradlepointecm.com/api/v2/accounts//",
                "app": "https://www.cradlepointecm.com/api/v2/device_apps/1442/",
                "created_at": "2021-02-10T22:44:22.763337+00:00",
                "id": "8613",
                "resource_url": "https://www.cradlepointecm.com/api/v2/device_app_versions/8613/",
                "state": "ready",
                "state_details": "",
                "updated_at": "2021-02-10T22:44:23.073839+00:00",
                "version": "2.0.0"
            }
        ],
        "meta": {
            "limit": 20,
            "next": null,
            "offset": 0,
            "previous": null
        }
    }
  • DELETE Example
  • Example curl DELETE request/response to the device_apps endpoint. This deletes the device version matching the ID passed in the route.

    curl -v -X DELETE -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/device_app_versions/8613/"

    Successful DELETE actions return a 204 response with no content in the body.

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.

Supported methods: GET.
  • failovers Endpoint Fields and Filters
  • This table lists the fields associated with the failovers endpoint. Fields with operators specified in the Filter column indicate that those fields can be used as filters.

    Parameter Data Type Filter Sort Expand Description
    account_id int Your account ID number
    ended_at datetime _exact=, _gt=, _gte=, _lt=, _lte= Datetime for when a failover event ended
    group_id int The ID of a group to view failover events
    limit int Number of records to return
    offset int
    router_id int The ID of a router to view failover events
    started_at datetime _exact=, _gt=, _gte=, _lt=, _lte= Datetime for when a failover event started

    Endpoint base path:

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

    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>
  • Tips for Using the NetCloud API
  • When making API calls with curl in a console session, it can be helpful to define variables for your API keys, payloads, and the base URL of the endpoint for re-use with each curl statement.
    Please note that the method for setting variables in your console of choice can vary depending on the console/OS used. These variable definition examples are BASH specific; other console tools can require slightly different syntax to define these variables in a console session.

    • X_ECM_API_ID="<X-ECM-API-ID>"
    • X_ECM_API_KEY="<X-ECM-API-KEY>"
    • X_CP_API_ID="<X-CP-API-ID>"
    • X_CP_API_KEY="<X-CP-API-KEY>"
    • -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY"
    • URL="https://www.cradlepointecm.com/api/v2/failovers/ "
    • BODY = -d '{"<field name>": "<field value>"}

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

  • GET Examples
  • Example curl GET request/response to the failovers endpoint without filters applied.

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/failovers/"

    Response body for curl GET example

    {
        "data": [
            {
                "account_id": 55993,
                "carrier_name": "Verizon",
                "current_wan_interface": "ethernet-wan",
                "current_wan_priority": 0.00088295,
                "data_usage": 65898,
                "elapsed_time": 32,
                "ended_at": "2019-10-22T20:26:34.033177+00:00",
                "group_id": 145242,
                "group_name": "2200",
                "percent_data_cap": null,
                "previous_wan_interface": "mdm-3983dbd5",
                "previous_wan_priority": 2.25014338,
                "router_id": 1507274,
                "router_name": "AER2200-120",
                "started_at": "2019-10-22T20:26:01.870771+00:00",
                "tenant_id": "0013800001TB9s1",
                "updated_at": "2019-10-22T20:27:32.390005+00:00",
                "uuid": "6a701002-652b-4137-9ead-5847ae338ccd"
            },
            {
                "account_id": 55993,
                "carrier_name": "Verizon",
                "current_wan_interface": "ethernet-wan",
                "current_wan_priority": 0.00088295,
                "data_usage": 74607,
                "elapsed_time": 96,
                "ended_at": "2019-10-22T20:32:24.293963+00:00",
                "group_id": 145242,
                "group_name": "2200",
                "percent_data_cap": null,
                "previous_wan_interface": "mdm-3983dbd5",
                "previous_wan_priority": 1.50014338,
                "router_id": 1507274,
                "router_name": "AER2200-120",
                "started_at": "2019-10-22T20:30:47.578229+00:00",
                "tenant_id": "0013800001TB9s1",
                "updated_at": "2019-10-22T20:33:18.376541+00:00",
                "uuid": "c3636db8-dd82-4974-a245-7ce872674afa"
            },
            ...
        ],
        "meta": {
            "limit": 20,
            "next": null,
            "offset": 0,
            "previous": null
        }
    }
     

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 firmwares endpoint to retrive information about NetCloud OS (NCOS) firmware builds.

Supported methods: GET.
  • firmwares Endpoint Fields and Filters
  • This table lists the fields associated with the firmwares endpoint. Fields with operators specified in the Filter column indicate that those fields can be used as filters.

    Parameter Data Type Filter Sort Expand Description
    built_at timestamp The time when the firmware image was built
    default_configuration json Default configuration for the firmware version
    expires_at timestamp The time when the firmware version expires
    hash string sha1sum hash of the firmware image
    id int =, __in Object ID
    is_deprecated boolean True if this firmware version has been deprecated
    product url Product this firmware is for
    released_at timestamp The time when the firmware was released
    resource_url url Object URL
    uploaded_at timestamp The time when the firmware image was uploaded to NCM
    url url URL of the firmware image
    version string =, __in Version of this firmware

    Endpoint base path:

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

    IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
    Correct format:    https://www.cradlepointecm.com/api/v2/<endpoint name>/
    Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
  • Tips for Using the NetCloud API
  • When making API calls with curl in a console session, it can be helpful to define variables for your API keys, payloads, and the base URL of the endpoint for re-use with each curl statement.
    Please note that the method for setting variables in your console of choice can vary depending on the console/OS used. These variable definition examples are BASH specific; other console tools can require slightly different syntax to define these variables in a console session.

    • X_ECM_API_ID="<X-ECM-API-ID>"
    • X_ECM_API_KEY="<X-ECM-API-KEY>"
    • X_CP_API_ID="<X-CP-API-ID>"
    • X_CP_API_KEY="<X-CP-API-KEY>"
    • -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY"
    • URL="https://www.cradlepointecm.com/api/v2/firmwares/"
    • BODY = -d '{"<field name>": "<field value>"}

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

  • GET Examples
  • Example curl GET request/response to the firmwares endpoint without filters applied.

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/firmwares/"

    Response body for curl GET example

    {
        "data": [
            {
                "built_at": "2013-07-02T17:08:47+00:00",
                "default_configuration": "https://www.cradlepointecm.com/api/v2/firmwares/1/default_configuration/",
                "expires_at": "2020-01-01T00:00:00+00:00",
                "hash": "25e8477e202e16dc64303c02bdc990d4d06a5daa",
                "id": "1",
                "is_deprecated": false,
                "product": "https://www.cradlepointecm.com/api/v2/products/4/",
                "released_at": "2013-07-02T17:08:47+00:00",
                "resource_url": "https://www.cradlepointecm.com/api/v2/firmwares/1/",
                "uploaded_at": "2013-07-03T17:59:24.167915+00:00",
                "url": "https://d251cfg5d9gyuq.cloudfront.net/CBR450-2013-07-02T17%3A08%3A47.bin",
                "version": "4.3.2"
            },
            {
                "built_at": "2013-07-02T16:34:08+00:00",
                "default_configuration": "https://www.cradlepointecm.com/api/v2/firmwares/2/default_configuration/",
                "expires_at": "2020-01-01T00:00:00+00:00",
                "hash": "516cdeaef3830f5558eb1276b4f6f573440f4082",
                "id": "2",
                "is_deprecated": true,
                "product": "https://www.cradlepointecm.com/api/v2/products/6/",
                "released_at": "2013-07-02T16:34:08+00:00",
                "resource_url": "https://www.cradlepointecm.com/api/v2/firmwares/2/",
                "uploaded_at": "2013-07-03T17:59:25.035746+00:00",
                "url": "https://d251cfg5d9gyuq.cloudfront.net/MBR1200B-2013-07-02T16%3A34%3A08.bin",
                "version": "4.3.2"
            },
            {
                "built_at": "2013-07-02T17:41:32+00:00",
                "default_configuration": "https://www.cradlepointecm.com/api/v2/firmwares/3/default_configuration/",
                "expires_at": "2020-01-01T00:00:00+00:00",
                "hash": "dc1578e687ca38964ddb59abe1c0f2fd8f001d70",
                "id": "3",
                "is_deprecated": true,
                "product": "https://www.cradlepointecm.com/api/v2/products/9/",
                "released_at": "2013-07-02T17:41:32+00:00",
                "resource_url": "https://www.cradlepointecm.com/api/v2/firmwares/3/",
                "uploaded_at": "2013-07-03T17:59:25.704200+00:00",
                "url": "https://d251cfg5d9gyuq.cloudfront.net/CBA750B-2013-07-02T17%3A41%3A32.bin",
                "version": "4.3.2"
            },
            {
                "built_at": "2013-07-02T16:51:19+00:00",
                "default_configuration": "https://www.cradlepointecm.com/api/v2/firmwares/4/default_configuration/",
                "expires_at": "2020-01-01T00:00:00+00:00",
                "hash": "01a79f1aee3a26618fe49c7e7e65eb6e24ae5046",
                "id": "4",
                "is_deprecated": false,
                "product": "https://www.cradlepointecm.com/api/v2/products/3/",
                "released_at": "2013-07-02T16:51:19+00:00",
                "resource_url": "https://www.cradlepointecm.com/api/v2/firmwares/4/",
                "uploaded_at": "2013-07-03T17:59:26.518240+00:00",
                "url": "https://d251cfg5d9gyuq.cloudfront.net/CBR400-2013-07-02T16%3A51%3A19.bin",
                "version": "4.3.2"
            },
            {
                "built_at": "2013-07-02T15:18:08+00:00",
                "default_configuration": "https://www.cradlepointecm.com/api/v2/firmwares/5/default_configuration/",
                "expires_at": "2020-01-01T00:00:00+00:00",
                "hash": "b57f285926f36147d1912d7c3072e798586a9e51",
                "id": "5",
                "is_deprecated": true,
                "product": "https://www.cradlepointecm.com/api/v2/products/7/",
                "released_at": "2013-07-02T15:18:08+00:00",
                "resource_url": "https://www.cradlepointecm.com/api/v2/firmwares/5/",
                "uploaded_at": "2013-07-03T17:59:27.308069+00:00",
                "url": "https://d251cfg5d9gyuq.cloudfront.net/IBR600-2013-07-02T15%3A18%3A08.bin",
                "version": "4.3.2"
            },
            {
                "built_at": "2013-07-02T15:56:43+00:00",
                "default_configuration": "https://www.cradlepointecm.com/api/v2/firmwares/6/default_configuration/",
                "expires_at": "2020-01-01T00:00:00+00:00",
                "hash": "f8c76946f67614da3db0b1a505ca718161c90851",
                "id": "6",
                "is_deprecated": true,
                "product": "https://www.cradlepointecm.com/api/v2/products/2/",
                "released_at": "2013-07-02T15:56:43+00:00",
                "resource_url": "https://www.cradlepointecm.com/api/v2/firmwares/6/",
                "uploaded_at": "2013-07-03T17:59:28.230896+00:00",
                "url": "https://d251cfg5d9gyuq.cloudfront.net/MBR1400v2-2013-07-02T15%3A56%3A43.bin",
                "version": "4.3.2"
            },
            {
                "built_at": "2013-07-02T16:15:37+00:00",
                "default_configuration": "https://www.cradlepointecm.com/api/v2/firmwares/7/default_configuration/",
                "expires_at": "2020-01-01T00:00:00+00:00",
                "hash": "5c824cc2f027313eb5ac85d8ced1c1e296976a5c",
                "id": "7",
                "is_deprecated": true,
                "product": "https://www.cradlepointecm.com/api/v2/products/1/",
                "released_at": "2013-07-02T16:15:37+00:00",
                "resource_url": "https://www.cradlepointecm.com/api/v2/firmwares/7/",
                "uploaded_at": "2013-07-03T17:59:29.642496+00:00",
                "url": "https://d251cfg5d9gyuq.cloudfront.net/MBR1400-2013-07-02T16%3A15%3A37.bin",
                "version": "4.3.2"
            },
            {
                "built_at": "2013-07-02T15:37:18+00:00",
                "default_configuration": "https://www.cradlepointecm.com/api/v2/firmwares/8/default_configuration/",
                "expires_at": "2020-01-01T00:00:00+00:00",
                "hash": "8e8e95fe5db91e2d9ebc7281a529a14eb8469f4a",
                "id": "8",
                "is_deprecated": true,
                "product": "https://www.cradlepointecm.com/api/v2/products/8/",
                "released_at": "2013-07-02T15:37:18+00:00",
                "resource_url": "https://www.cradlepointecm.com/api/v2/firmwares/8/",
                "uploaded_at": "2013-07-03T17:59:30.400223+00:00",
                "url": "https://d251cfg5d9gyuq.cloudfront.net/IBR650-2013-07-02T15%3A37%3A18.bin",
                "version": "4.3.2"
            },
            {
                "built_at": "2013-08-12T16:32:13+00:00",
                "default_configuration": "https://www.cradlepointecm.com/api/v2/firmwares/15/default_configuration/",
                "expires_at": "2020-01-01T00:00:00+00:00",
                "hash": "5d8b5ebfceda731472f609009f0783981f0c462d",
                "id": "15",
                "is_deprecated": false,
                "product": "https://www.cradlepointecm.com/api/v2/products/6/",
                "released_at": "2013-08-12T16:32:13+00:00",
                "resource_url": "https://www.cradlepointecm.com/api/v2/firmwares/15/",
                "uploaded_at": "2013-09-11T23:59:38.141907+00:00",
                "url": "https://d251cfg5d9gyuq.cloudfront.net/MBR1200B-2013-08-12T16%3A32%3A13.bin",
                "version": "4.4.0"
            },
            {
                "built_at": "2013-08-12T17:09:53+00:00",
                "default_configuration": "https://www.cradlepointecm.com/api/v2/firmwares/16/default_configuration/",
                "expires_at": "2020-01-01T00:00:00+00:00",
                "hash": "50ede08a8fa0533ab908f336140c0c924cf52f6d",
                "id": "16",
                "is_deprecated": false,
                "product": "https://www.cradlepointecm.com/api/v2/products/9/",
                "released_at": "2013-08-12T17:09:53+00:00",
                "resource_url": "https://www.cradlepointecm.com/api/v2/firmwares/16/",
                "uploaded_at": "2013-09-11T23:59:39.244468+00:00",
                "url": "https://d251cfg5d9gyuq.cloudfront.net/CBA750B-2013-08-12T17%3A09%3A53.bin",
                "version": "4.4.0"
            },
            {
                "built_at": "2013-08-12T15:05:51+00:00",
                "default_configuration": "https://www.cradlepointecm.com/api/v2/firmwares/17/default_configuration/",
                "expires_at": "2020-01-01T00:00:00+00:00",
                "hash": "febe611670c83608f122fef654d32a55cd55d70d",
                "id": "17",
                "is_deprecated": false,
                "product": "https://www.cradlepointecm.com/api/v2/products/7/",
                "released_at": "2013-08-12T15:05:51+00:00",
                "resource_url": "https://www.cradlepointecm.com/api/v2/firmwares/17/",
                "uploaded_at": "2013-09-11T23:59:40.485441+00:00",
                "url": "https://d251cfg5d9gyuq.cloudfront.net/IBR600-2013-08-12T15%3A05%3A51.bin",
                "version": "4.4.0"
            },
            {
                "built_at": "2013-08-12T15:50:22+00:00",
                "default_configuration": "https://www.cradlepointecm.com/api/v2/firmwares/18/default_configuration/",
                "expires_at": "2020-01-01T00:00:00+00:00",
                "hash": "ccb0f716bf4bd296e2ff1e11a96b8931742a35ad",
                "id": "18",
                "is_deprecated": false,
                "product": "https://www.cradlepointecm.com/api/v2/products/2/",
                "released_at": "2013-08-12T15:50:22+00:00",
                "resource_url": "https://www.cradlepointecm.com/api/v2/firmwares/18/",
                "uploaded_at": "2013-09-11T23:59:41.390803+00:00",
                "url": "https://d251cfg5d9gyuq.cloudfront.net/MBR1400v2-2013-08-12T15%3A50%3A22.bin",
                "version": "4.4.0"
            },
            {
                "built_at": "2013-08-12T16:11:11+00:00",
                "default_configuration": "https://www.cradlepointecm.com/api/v2/firmwares/19/default_configuration/",
                "expires_at": "2020-01-01T00:00:00+00:00",
                "hash": "fa7ba9b01208bec3348a7ad9b9d2e84aadda642c",
                "id": "19",
                "is_deprecated": false,
                "product": "https://www.cradlepointecm.com/api/v2/products/1/",
                "released_at": "2013-08-12T16:11:11+00:00",
                "resource_url": "https://www.cradlepointecm.com/api/v2/firmwares/19/",
                "uploaded_at": "2013-09-11T23:59:42.169480+00:00",
                "url": "https://d251cfg5d9gyuq.cloudfront.net/MBR1400-2013-08-12T16%3A11%3A11.bin",
                "version": "4.4.0"
            },
            {
                "built_at": "2013-08-12T15:27:33+00:00",
                "default_configuration": "https://www.cradlepointecm.com/api/v2/firmwares/20/default_configuration/",
                "expires_at": "2020-01-01T00:00:00+00:00",
                "hash": "344df0ea31fad4ed57e63995bf8c8832d69db60b",
                "id": "20",
                "is_deprecated": false,
                "product": "https://www.cradlepointecm.com/api/v2/products/8/",
                "released_at": "2013-08-12T15:27:33+00:00",
                "resource_url": "https://www.cradlepointecm.com/api/v2/firmwares/20/",
                "uploaded_at": "2013-09-11T23:59:42.906921+00:00",
                "url": "https://d251cfg5d9gyuq.cloudfront.net/IBR650-2013-08-12T15%3A27%3A33.bin",
                "version": "4.4.0"
            },
            {
                "built_at": "2013-10-07T11:26:12+00:00",
                "default_configuration": "https://www.cradlepointecm.com/api/v2/firmwares/24/default_configuration/",
                "expires_at": "2020-01-01T00:00:00+00:00",
                "hash": "2bf48e15384582d703064889dd968862a921fef6",
                "id": "24",
                "is_deprecated": false,
                "product": "https://www.cradlepointecm.com/api/v2/products/6/",
                "released_at": "2013-10-07T11:26:12+00:00",
                "resource_url": "https://www.cradlepointecm.com/api/v2/firmwares/24/",
                "uploaded_at": "2013-10-08T00:59:47.836270+00:00",
                "url": "https://d251cfg5d9gyuq.cloudfront.net/MBR1200B-2013-10-07T11%3A26%3A12.bin",
                "version": "4.4.2"
            },
            {
                "built_at": "2013-10-07T12:37:37+00:00",
                "default_configuration": "https://www.cradlepointecm.com/api/v2/firmwares/25/default_configuration/",
                "expires_at": "2020-01-01T00:00:00+00:00",
                "hash": "de683b3704e0dc6e2be18709cf666209a12b4f8a",
                "id": "25",
                "is_deprecated": false,
                "product": "https://www.cradlepointecm.com/api/v2/products/9/",
                "released_at": "2013-10-07T12:37:37+00:00",
                "resource_url": "https://www.cradlepointecm.com/api/v2/firmwares/25/",
                "uploaded_at": "2013-10-08T00:59:52.284638+00:00",
                "url": "https://d251cfg5d9gyuq.cloudfront.net/CBA750B-2013-10-07T12%3A37%3A37.bin",
                "version": "4.4.2"
            },
            {
                "built_at": "2013-10-07T10:02:37+00:00",
                "default_configuration": "https://www.cradlepointecm.com/api/v2/firmwares/26/default_configuration/",
                "expires_at": "2020-01-01T00:00:00+00:00",
                "hash": "c78ce23fa43047789dcbfe641ef6b5dd9a74553b",
                "id": "26",
                "is_deprecated": false,
                "product": "https://www.cradlepointecm.com/api/v2/products/7/",
                "released_at": "2013-10-07T10:02:37+00:00",
                "resource_url": "https://www.cradlepointecm.com/api/v2/firmwares/26/",
                "uploaded_at": "2013-10-08T00:59:54.135536+00:00",
                "url": "https://d251cfg5d9gyuq.cloudfront.net/IBR600-2013-10-07T10%3A02%3A37.bin",
                "version": "4.4.2"
            },
            {
                "built_at": "2013-10-07T10:46:04+00:00",
                "default_configuration": "https://www.cradlepointecm.com/api/v2/firmwares/27/default_configuration/",
                "expires_at": "2020-01-01T00:00:00+00:00",
                "hash": "37a13ea54efdd2c155fc9b96b5194810fefd126d",
                "id": "27",
                "is_deprecated": false,
                "product": "https://www.cradlepointecm.com/api/v2/products/2/",
                "released_at": "2013-10-07T10:46:04+00:00",
                "resource_url": "https://www.cradlepointecm.com/api/v2/firmwares/27/",
                "uploaded_at": "2013-10-08T00:59:55.300692+00:00",
                "url": "https://d251cfg5d9gyuq.cloudfront.net/MBR1400v2-2013-10-07T10%3A46%3A04.bin",
                "version": "4.4.2"
            },
            {
                "built_at": "2013-10-07T11:06:13+00:00",
                "default_configuration": "https://www.cradlepointecm.com/api/v2/firmwares/28/default_configuration/",
                "expires_at": "2020-01-01T00:00:00+00:00",
                "hash": "72d96f027a4dfb8133a513c45409d997a51e5d56",
                "id": "28",
                "is_deprecated": false,
                "product": "https://www.cradlepointecm.com/api/v2/products/1/",
                "released_at": "2013-10-07T11:06:13+00:00",
                "resource_url": "https://www.cradlepointecm.com/api/v2/firmwares/28/",
                "uploaded_at": "2013-10-08T00:59:56.957464+00:00",
                "url": "https://d251cfg5d9gyuq.cloudfront.net/MBR1400-2013-10-07T11%3A06%3A13.bin",
                "version": "4.4.2"
            },
            {
                "built_at": "2013-10-07T10:23:47+00:00",
                "default_configuration": "https://www.cradlepointecm.com/api/v2/firmwares/29/default_configuration/",
                "expires_at": "2020-01-01T00:00:00+00:00",
                "hash": "5549f9e11b5e0f54e1e2b58be501604d48ad4f7f",
                "id": "29",
                "is_deprecated": false,
                "product": "https://www.cradlepointecm.com/api/v2/products/8/",
                "released_at": "2013-10-07T10:23:47+00:00",
                "resource_url": "https://www.cradlepointecm.com/api/v2/firmwares/29/",
                "uploaded_at": "2013-10-08T01:00:03.272843+00:00",
                "url": "https://d251cfg5d9gyuq.cloudfront.net/IBR650-2013-10-07T10%3A23%3A47.bin",
                "version": "4.4.2"
            }
        ],
        "meta": {
            "limit": 20,
            "next": "https://www.cradlepointecm.com/api/v2/firmwares/?limit=20&offset=20",
            "offset": 0,
            "previous": null
        }
    }

    Example curl GET request/response to the firmwares endpoint with the ID filter applied. This retrieves information for the firmware package with the ID "2."

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/firmwares/?id=2"

    Response body for curl GET example

    {
        "data": [
            {
                "built_at": "2013-07-02T16:34:08+00:00",
                "default_configuration": "https://www.cradlepointecm.com/api/v2/firmwares/2/default_configuration/",
                "expires_at": "2020-01-01T00:00:00+00:00",
                "hash": "516cdeaef3830f5558eb1276b4f6f573440f4082",
                "id": "2",
                "is_deprecated": true,
                "product": "https://www.cradlepointecm.com/api/v2/products/6/",
                "released_at": "2013-07-02T16:34:08+00:00",
                "resource_url": "https://www.cradlepointecm.com/api/v2/firmwares/2/",
                "uploaded_at": "2013-07-03T17:59:25.035746+00:00",
                "url": "https://d251cfg5d9gyuq.cloudfront.net/MBR1200B-2013-07-02T16%3A34%3A08.bin",
                "version": "4.3.2"
            }
        ],
        "meta": {
            "limit": 20,
            "next": null,
            "offset": 0,
            "previous": null
        }
    }  
      

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 forwarding_lan_details endpoint to retrieve information about the settings for forwarding LAN traffic into NetCloud Perimeter, such as enabled, network_id, and auto_whitelist.This endpoint can be used with the router_lans and overlay_network_bindings endpoints to deploy a NetCloud Perimeter Gateway on a device. See the Create a NetCloud Perimter Gateway section below for more information.

Supported methods: GET, POST, PUT, DELETE.
  • forwarding_lan_details Endpoint Fields and Filters
  • This table lists the fields associated with the forwarding_lan_details endpoint. Fields with operators specified in the Filter column indicate that those fields can be used as filters.

    Parameter Data Type Filter Sort Expand Description Permissions
    auto_whitelist boolean = Auto whitelist status Read/Write
    enabled boolean = Enabled status Read/Write
    id* int =, __in ID of the forwarding_lan_details record Read
    lan url =, __in The LAN where the traffic is being forwarded Read/Write
    network_id int =, __in Network ID Read/Write
    overlay_network_binding url =, __in Overlay network ID Read/Write
    Note: * indicates the attribute is required for PUT and DELETE requests.

    Endpoint base path:

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

    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>
  • Tips for Using the NetCloud API
  • When making API calls with curl in a console session, it can be helpful to define variables for your API keys, payloads, and the base URL of the endpoint for re-use with each curl statement.
    Please note that the method for setting variables in your console of choice can vary depending on the console/OS used. These variable definition examples are BASH specific; other console tools can require slightly different syntax to define these variables in a console session.

    • X_ECM_API_ID="<X-ECM-API-ID>"
    • X_ECM_API_KEY="<X-ECM-API-KEY>"
    • X_CP_API_ID="<X-CP-API-ID>"
    • X_CP_API_KEY="<X-CP-API-KEY>"
    • -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY"
    • URL="https://www.cradlepointecm.com/api/v2/forwarding_lan_details/"
    • BODY = -d '{"<field name>": "<field value>"}

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

  • Create a NetCloud Perimeter Gateway
  • Use the following steps to install the NetCloud Perimeter (NCP) Gateway Client on a device using the NetCloud API.

    1. Send a GET request to the router_lans endpoint and filter by router ID. Collect the router_lans IDs.
    2. Send a GET request to the forwarding_lan_details endpoint and filter by the previously collected router_lans IDs. Collect the forwarding_lan_details IDs.
    3. Use router_lans IDS and forwarding_lans_details IDs collected in the previous steps in the body of a POST request to overlay_network_bindings. This installs the NCP Gateway Client and binds it to an NCP network.

    1. GET request example to the router_lans endpoint to get the router_lans ID(s)

    curl -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/router_lans/2222/"
        

    Response example. Note the "id" field value (2222).

    {
        "data": [
            {
                "account": "https://www.cradlepointecm.com/api/v2/accounts/",
                "created_at": "2019-04-12T14:28:38.423098+00:00",
                "enabled": true,
                "id": "2222",
                "ip_address": "192.168.17.1",
                "name": "Primary LAN",
                "netmask": "255.255.255.0",
                "resource_url": "https://www.cradlepointecm.com/api/v2/router_lans/2222/",
                "router": "https://www.cradlepointecm.com/api/v2/routers/12345/",
                "updated_at": "2020-12-21T00:22:56.363885+00:00"
            },
            {
                "meta": {
                    "limit": 20,
                    "next": null,
                    "offset": 0,
                    "previous": null
                }
            }
        ]
    }
        

    2. GET request example to the forwarding_lan_details endpoint to get the forwarding_lan_details ID(s).

    curl -X -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" -H "Content-Type: application/json" "https://www.cradlepointecm.com/api/v2/forwarding_lan_details/3333/"
      

    Response example. Note the "id" field value (3333).

    {
        "data": [
            {
                "auto_whitelist": false,
                "enabled": false,
                "id": "3333",
                "lan": "https://www.cradlepointecm.com/api/v2/router_lans/4444/",
                "network_id": null,
                "overlay_network_binding": null,
                "resource_url": "https://www.cradlepointecm.com/api/v2/forwarding_lan_details/3333/"
            },
            {
                "meta": {
                    "limit": 20,
                    "next": null,
                    "offset": 0,
                    "previous": null
                }
            }
        ]
    }
        

    3. POST request to overlay_network_bindings to create the NCP Gateway Client

    curl -H -x POST "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" -H "Content-Type: application/json" 
    -d '{
        "account": "https://www.cradlepointecm.com/api/v2/accounts/1111/",
        "router": "https://www.cradlepointecm.com/api/v2/routers/12345/",
        "network_id": 3333,
        "forwarding_lan_details": [
            {
                "enabled": true,
                "auto_whitelist": false,
                "lan": "https://www.cradlepointecm.com/api/v2/router_lans/4444/"
            },
            {
                "enabled": true,
                "auto_whitelist": false,
                "lan": "https://www.cradlepointecm.com/api/v2/router_lans/4444/"
            }
        ]
    }'
    "https://www.cradlepointecm.com/api/v2/overlay_network_bindings/"
        
  • GET Examples
  • Example curl GET request/response to the forwarding_lan_details endpoint without filters applied.

    curl -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/forwarding_lan_details/"
      

    Response body for curl GET example

    {
        "data": [
            {
                "auto_whitelist": false,
                "enabled": false,
                "id": "1",
                "lan": "https://www.cradlepointecm.com/api/v2/router_lans/1/",
                "network_id": 3333,
                "overlay_network_binding": null,
                "resource_url": "https://www.cradlepointecm.com/api/v2/forwarding_lan_details/1/"
            }
        ],
        "meta": {
            "limit": 20,
            "next": null,
            "offset": 0,
            "previous": null
        }
    }
     
  • POST Examples
  • Example curl POST request/response to the forwarding_lan_details endpoint.

    curl -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" -H "Content-Type: application/json" -d '{"auto_whitelist":true, "enabled": false, "id":"1", "lan": "https://www.cradlepointecm.com/api/v2/router_lans/1/", "network_id": 3333, "overlay_network_binding": null}' https://www.cradlepointecm.com/api/v2/forwarding_lan_details/        
        

    Response body for curl POST example

    {
        "auto_whitelist": false,
        "enabled": false,
        "id": "1",
        "lan": "https://www.cradlepointecm.com/api/v2/router_lans/1/",
        "network_id": 3333,
        "overlay_network_binding": null,
        "resource_url": "https://www.cradlepointecm.com/api/v2/forwarding_lan_details/"
    }
        
  • PUT Examples
  • Example curl PUT request/response to the forwarding_lan_details endpoint.

    curl -X PUT -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" -H "Content-Type: application/json" -d '{"enabled":true}' "https://www.cradlepointecm.com/api/v2/forwarding_lan_details/1/"
        

    Response body for curl PUT example

    {
        "auto_whitelist": true,
        "enabled": true,
        "id": "1",
        "lan": "https://www.cradlepointecm.com/api/v2/router_lans/1/",
        "network_id": 3333,
        "overlay_network_binding": null,
        "resource_url": "https://www.cradlepointecm.com/api/v2/forwarding_lan_details/1/"
    }        
        
  • DELETE Example
  • Example curl DELETE request/response to the forwarding_lan_details endpoint. This deletes the group matching the ID passed in the route.

    curl -X DELETE -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" -H "Content-Type: application/json" "https://www.cradlepointecm.com/api/v2/forwarding_lan_details/1/"    
      

    Successful DELETE actions return a 204 response with no content in the body.

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

Supported methods: GET, POST, PUT, DELETE.
  • Groups Endpoint Fields and Filters
  • This table lists the fields associated with the groups endpoint. Fields with operators specified in the Filter column indicate that those fields can be used as filters.

    Parameter Data Type Filter Sort Expand Description Permissions
    account* url =, __in Account which owns the object Read/Write
    configuration json Configuration for the group Read/Write
    device_type string =, __in Type of device, e.g. router or access point Read Only
    id int =, __in Object ID Read Only
    name* string =, __in Name of the group Read/Write
    product* url Product type for the group Read/Write
    resource_url url Object URL Read/Write
    target_firmware* url Firmware version for the group Read/Write
    Note: * indicates the attribute is required for PUT and POST requests.

    Endpoint base path:

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

    IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
    Correct format:    https://www.cradlepointecm.com/api/v2/<endpoint name>/
    Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
  • Tips for Using the NetCloud API
  • When making API calls with curl in a console session, it can be helpful to define variables for your API keys, payloads, and the base URL of the endpoint for re-use with each curl statement.
    Please note that the method for setting variables in your console of choice can vary depending on the console/OS used. These variable definition examples are BASH specific; other console tools can require slightly different syntax to define these variables in a console session.

    • X_ECM_API_ID="<X-ECM-API-ID>"
    • X_ECM_API_KEY="<X-ECM-API-KEY>"
    • X_CP_API_ID="<X-CP-API-ID>"
    • X_CP_API_KEY="<X-CP-API-KEY>"
    • -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY"
    • URL="https://www.cradlepointecm.com/api/v2/accounts/"
    • BODY = -d '{"<field name>": "<field value>"}

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

  • GET Examples
  • Example curl GET request/response to the groups endpoint without filters applied.

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/groups/"

    Response body for curl GET example

    {
        "data": [
            {
                "account": "https://www.cradlepointecm.com/api/v2/accounts/<account number>/",
                "configuration": [
                    {},
                    []
                ],
                "device_type": "access_point",
                "id": "85136",
                "name": "AP22 Group",
                "product": "https://www.cradlepointecm.com/api/v2/products/48/",
                "resource_url": "https://www.cradlepointecm.com/api/v2/groups/85136/",
                "target_firmware": "https://www.cradlepointecm.com/api/v2/firmwares/877/"
            },
            {
                "account": "https://www.cradlepointecm.com/api/v2/accounts/<account number>/",
                "configuration": [
                    {},
                    []
                ],
                "device_type": "router",
                "id": "155407",
                "name": "AER3100 Group",
                "product": "https://www.cradlepointecm.com/api/v2/products/28/",
                "resource_url": "https://www.cradlepointecm.com/api/v2/groups/155407/",
                "target_firmware": "https://www.cradlepointecm.com/api/v2/firmwares/1529/"
            },
            ...
         ]
    }     
    
            

    Example curl GET request/response to the groups endpoint with the name filter applied. This retrieves the group with the name matching "AP-22 Group".

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/groups/?name=AP22%20Group"

    Response body for curl GET example

    {
        "data": [
            {
                "account": "https://www.cradlepointecm.com/api/v2/accounts/<account number>/",
                "configuration": [
                    {},
                    []
                ],
                "device_type": "access_point",
                "id": "85136",
                "name": "AP22 Group",
                "product": "https://www.cradlepointecm.com/api/v2/products/48/",
                "resource_url": "https://www.cradlepointecm.com/api/v2/groups/85136/",
                "target_firmware": "https://www.cradlepointecm.com/api/v2/firmwares/877/"
            }
        ],
        "meta": {
            "limit": 20,
            "next": null,
            "offset": 0,
            "previous": null
        }
    }
            
  • POST Examples
  • Example curl POST request/response to the groups endpoint. This creates a new group in the specified account.

    curl -v -X POST -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY " -H "Content-Type:application/json" "https://www.cradlepointecm.com/api/v2/groups/" -d '{
            "account": "https://www.cradlepointecm.com/api/v2/accounts/<account number>/",
            "name": "IBR1100",
            "product": "https://www.cradlepointecm.com/api/v2/products/23/",
            "target_firmware": "https://www.cradlepointecm.com/api/v2/firmwares/29/"
            }'

    Response body for curl POST example

    {
        "account": "https://www.cradlepointecm.com/api/v2/accounts/35065/",
        "configuration": [
            {},
            []
        ],
        "device_type": "router",
        "id": "230007",
        "name": "IBR1100",
        "product": "https://www.cradlepointecm.com/api/v2/products/23/",
        "resource_url": "https://www.cradlepointecm.com/api/v2/groups/",
        "target_firmware": "https://www.cradlepointecm.com/api/v2/firmwares/29/"
    }
        
  • PUT Examples
  • Example curl PUT request/response to the groups endpoint. This updates the name of the group matching the ID "230007".

    curl -v -X PUT -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" -H "Content-Type:application/json" "https://www.cradlepointecm.com/api/v2/groups/230007/" -d '{
            "name": "IBR1100 Group"

    Response body for curl PUT example

    {
        "account": "https://www.cradlepointecm.com/api/v2/accounts/<account number>/",
        "configuration": [
            {},
            []
        ],
        "device_type": "router",
        "id": "230007",
        "name": "IBR1100 Group",
        "product": "https://www.cradlepointecm.com/api/v2/products/23/",
        "resource_url": "https://www.cradlepointecm.com/api/v2/groups/230007/",
        "target_firmware": "https://www.cradlepointecm.com/api/v2/firmwares/29/"
    }
        
  • DELETE Example
  • Example curl DELETE request/response to the groups endpoint. This deletes the group matching the ID passed in the route.

    curl -v -X DELETE -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/groups/230007/"

    Successful DELETE actions return a 204 response with no content in the body.

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.

Supported methods: GET.
  • historical_locations Endpoint Fields and Filters
  • This table lists the fields associated with the historical_locations endpoint. Fields with operators specified in the Filter column indicate that those fields can be used as filters.

    Parameter Data Type Filter Sort Expand Description
    accuracy int Calculated accuracy of coordinates, based on latitude.
    carrier_id string The carrier the modem is currently registered with
    cinr double Carrier to Interference plus Noise Ratio (dB)
    created_at timestamp =, __gt, __lt Time the sample was created
    created_at_timeuuid timeuuid =, __in, __gt, __gte, __lt, __lte A unique ID associated with the created_at timestamp. Ordering by the ID is equivalent to time ordering. This field can identify a specific record or be used for paging.
    dbm int Strength of received signal (dBm)
    ecio int Ec/Io, the ratio of average channel power to total signal power (dB)
    latitude int A device's relative position north or south on the Earth's surface, in degrees from the Equator
    longitude int A device's relative position east or west on the Earth's surface, in degrees from the prime meridian
    mph float Speed of the vehicle carrying the device
    net_device_name float Network device's name, e.g. 'ethernet-wan', 'lte-1234abcd', 'mdm-dcba4321'
    rfband string Indicates the Radio Frequency Band that is currently being used by the modem module
    rfband_5g string Indicates the 5G Radio Frequency Band that is currently being used by the modem module
    router URL = The ID of the device providing the location information
    rsrp double LTE reference signal receive power
    rsrp_5g double 5G reference signal receive power
    rsrq int LTE reference signal receive quality
    rsrq_5g int 5G reference signal receive quality
    rssi int Received Signal Strength Indication (units vary with manufacturer)
    Note: Only for WiFi as WAN interfaces
    signal_percent int Percent signal strength, derived heuristically from other values
    sinr double Signal to Interference plus Noise Ratio (dB)
    sinr_5g double 5G Signal to Interference plus Noise Ratio (dB)
    summary string Connected status of the net device.
    Note: * indicates the attribute is required for PUT and POST requests.

    Endpoint base path:

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

    IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
    Correct format:    https://www.cradlepointecm.com/api/v2/<endpoint name>/
    Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
  • Tips for Using the NetCloud API
  • When making API calls with curl in a console session, it can be helpful to define variables for your API keys, payloads, and the base URL of the endpoint for re-use with each curl statement.
    Please note that the method for setting variables in your console of choice can vary depending on the console/OS used. These variable definition examples are BASH specific; other console tools can require slightly different syntax to define these variables in a console session.

    • X_ECM_API_ID="<X-ECM-API-ID>"
    • X_ECM_API_KEY="<X-ECM-API-KEY>"
    • X_CP_API_ID="<X-CP-API-ID>"
    • X_CP_API_KEY="<X-CP-API-KEY>"
    • -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY"
    • URL="https://www.cradlepointecm.com/api/v2/historical_locations/"
    • BODY = -d '{"<field name>": "<field value>"}

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

  • GET Examples
  • Example curl GET request/response to the historical_locations endpoint.

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/historical_locations/?router=2162719"

    Response body for curl GET example. This example is one historical_locations record from a recordset of hundreds of location records for the specified router.

        {
          "created_at" : "2021-02-06T21:38:01.447270Z",
          "ecio" : null,
          "rfband_5g" : null,
          "rsrq_5g" : null,
          "net_device_name" : "wwan-60:38:e0:35:f2:96:2_4G-1",
          "rsrq" : null,
          "mph" : 52.71,
          "signal_percent" : null,
          "sinr" : null,
          "longitude" : -116.07866,
          "dbm" : null,
          "rfband" : null,
          "created_at_timeuuid" : "964d01fa-68c3-11eb-8000-000000000000",
          "latitude" : 44.82413,
          "cinr" : null,
          "carrier_id" : null,
          "sinr_5g" : null,
          "rsrp_5g" : null,
          "summary" : null,
          "rssi" : null,
          "rsrp" : null,
          "accuracy" : 2
       }
     

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.

Supported methods: GET, POST, PUT, DELETE.
  • locations Endpoint Fields and Filters
  • This table lists the fields associated with the locations endpoint. Fields with operators specified in the Filter column indicate that those fields can be used as filters.

    Parameter Data Type Filter Sort Expand Description Permissions
    account* url Account which owns the object Read/Write
    accuracy* int Indicates accuracy range of location coordinates in meters Read/Write
    id int =, __in Unique identifier of a location object. Location object unique identifiers are generated when location objects are created via calls to this endpoint using POST, as well as locations gathered from the device when Location Services are enabled. Read/Write
    latitude* int A device's relative position north or south on the Earth's surface, in degrees from the Equator Read/Write
    longitude* int A device's relative position east or west on the Earth's surface, in degrees from the prime meridian Read/Write
    method* string Method used to determine location (eg. "gps" or "manual") Read/Write
    resource_url url Object URL Read/Write
    router* url =, __in Device that the location is associated with Read/Write
    updated_at timestamp Time of the last location update Read/Write
    Note: * indicates the attribute is required for PUT and POST requests.

    Endpoint base path:

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

    IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
    Correct format:    https://www.cradlepointecm.com/api/v2/<endpoint name>/
    Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
  • Tips for Using the NetCloud API
  • When making API calls with curl in a console session, it can be helpful to define variables for your API keys, payloads, and the base URL of the endpoint for re-use with each curl statement.
    Please note that the method for setting variables in your console of choice can vary depending on the console/OS used. These variable definition examples are BASH specific; other console tools can require slightly different syntax to define these variables in a console session.

    • X_ECM_API_ID="<X-ECM-API-ID>"
    • X_ECM_API_KEY="<X-ECM-API-KEY>"
    • X_CP_API_ID="<X-CP-API-ID>"
    • X_CP_API_KEY="<X-CP-API-KEY>"
    • -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY"
    • URL="https://www.cradlepointecm.com/api/v2/locations/"
    • BODY = -d '{"<field name>": "<field value>"}

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

  • GET Examples
  • Example curl GET request/response to the locations endpoint without filters applied.

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/locations/"

    Response body for curl GET example

    {
        "data": [
            {
                "account": "https://www.cradlepointecm.com/api/v2/accounts/<account number>/",
                "accuracy": 0,
                "id": "731218",
                "latitude": 43.5783243,
                "longitude": -116.1913274,
                "method": "manual",
                "resource_url": "https://www.cradlepointecm.com/api/v2/locations/731218/",
                "router": "https://www.cradlepointecm.com/api/v2/routers/2162719/",
                "updated_at": "2021-01-25T16:04:34.731183+00:00"
            }
        ],
        "meta": {
            "limit": 20,
            "next": null,
            "offset": 0,
            "previous": null
        }
    }
     

    Example curl GET request/response to the locations endpoint with the ID filter applied.

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/locations/?id=731218"

    Response body for curl GET example

    {
                "data": [
                    {
                        "account": "https://www.cradlepointecm.com/api/v2/accounts/<account number>/",
                        "accuracy": 0,
                        "id": "731218",
                        "latitude": 43.5783243,
                        "longitude": -116.1913274,
                        "method": "manual",
                        "resource_url": "https://www.cradlepointecm.com/api/v2/locations/731218/",
                        "router": "https://www.cradlepointecm.com/api/v2/routers/2162719/",
                        "updated_at": "2021-01-25T16:04:34.731183+00:00"
                    }
                ],
                "meta": {
                    "limit": 20,
                    "next": null,
                    "offset": 0,
                    "previous": null
                }
            }
  • POST Examples
  • Example curl POST request/response to the locations endpoint. This creates a new location record in the specified account.

          curl -v -X POST -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" -H "Content-Type:application/json" "https://www.cradlepointecm.com/api/v2/locations/" -d '        {
            "account": "https://www.cradlepointecm.com/api/v2/accounts/<account number>/",
            "accuracy": "0",
            "method": "manual",
            "latitude": "54.6197012",
            "longitude": -116.2059159,
            "router": "https://www.cradlepointecm.com/api/v2/routers/<account number>/"
        }'
        

    Response body for curl POST example

          {
            "account": "https://www.cradlepointecm.com/api/v2/accounts/<account number>/",
            "accuracy": 0,
            "id": "763427",
            "latitude": 54.6197012,
            "longitude": -116.2059159,
            "method": "manual",
            "resource_url": "https://www.cradlepointecm.com/api/v2/locations/",
            "router": "https://www.cradlepointecm.com/api/v2/routers/2162719/",
            "updated_at": "2021-02-17T17:36:53.239075+00:00"
        }
        
  • PUT Examples
  • Example curl PUT request/response to the locations endpoint. This updates the latitude value from 43 to 44.

    curl -v -X PUT -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" -H "Content-Type:application/json" "https://www.cradlepointecm.com/api/v2/locations/731218/" -d '
          {
              "accuracy": 0,
              "latitude": "44.6197012",
              "longitude": "-116.2059159"
          }
    '

    Response body for curl PUT example

    {
          "account": "https://www.cradlepointecm.com/api/v2/accounts/<account number>/",
          "accuracy": 0,
          "id": "731218",
          "latitude": 44.6197012,
          "longitude": -116.2059159,
          "method": "manual",
          "resource_url": "https://www.cradlepointecm.com/api/v2/locations/731218/",
          "router": "https://www.cradlepointecm.com/api/v2/routers/2162719/",
          "updated_at": "2021-02-17T16:51:50.499149+00:00"
      }
  • DELETE Example
  • Example curl DELETE request/response to the locations endpoint. This deletes the location record matching the ID passed in the route.

    curl -v -X DELETE -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/locations/731218/"

    Successful DELETE actions return a 204 response with no content in the body.

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 net_device_health endpoint to view the quality and strength of the cellular signal, expressed as device uptime in the cellular_health_score field, for your Cradlepoint devices.

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

  • Uptime data is available for routers with NCOS 6.2 or higher
  • Routers must be managed by NCM in order for statistics to be gathered on them.
  • Uptime statistics are calculated at the end of each day. A "day" is defined by a 24-hour period beginning at midnight UTC (Coordinate Universal Time).
  • Removing a router from NCM, or moving a router to a new group, does not affect the historically-collected, group-uptime data. The history will not change if a router's group membership changes.
Supported methods: GET.
  • net_device_health Endpoint Fields and Filters
  • This table lists the fields associated with the net_device_health endpoint. Fields with operators specified in the Filter column indicate that those fields can be used as filters.

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

    Endpoint base path:

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

    IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
    Correct format:    https://www.cradlepointecm.com/api/v2/<endpoint name>/
    Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
  • Tips for Using the NetCloud API
  • When making API calls with curl in a console session, it can be helpful to define variables for your API keys, payloads, and the base URL of the endpoint for re-use with each curl statement.
    Please note that the method for setting variables in your console of choice can vary depending on the console/OS used. These variable definition examples are BASH specific; other console tools can require slightly different syntax to define these variables in a console session.

    • X_ECM_API_ID="<X-ECM-API-ID>"
    • X_ECM_API_KEY="<X-ECM-API-KEY>"
    • X_CP_API_ID="<X-CP-API-ID>"
    • X_CP_API_KEY="<X-CP-API-KEY>"
    • -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY"
    • URL="https://www.cradlepointecm.com/api/v2/net_device_health/"
    • BODY = -d '{"<field name>": "<field value>"}

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

  • GET Examples
  • Example curl GET request/response to the net_device_health endpoint with the net_device filter applied. Omit the net_device filter to retrieve net_device_health records for all net devices in your account.

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/net_device_health/?net_device=<net device id>"

    Response body for curl GET example

        {
          "data" : [
             {
                "id" : "28298558",
                "cellular_health_score" : 82,
                "resource_url" : "https://qa4.cradlepointecm.com/api/v2/net_device_health/28298558/",
                "cellular_health_category" : "excellent",
                "net_device" : "https://qa4.cradlepointecm.com/api/v2/net_devices/<net device id>/"
             }
          ],
          "meta" : {
             "limit" : 20,
             "previous" : null,
             "offset" : 0,
             "next" : null
          }
       }
     

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.

Supported methods: GET.
  • net_device_metrics Endpoint Fields and Filters
  • This table lists the fields associated with the net_device_metrics endpoint. Fields with operators specified in the Filter column indicate that those fields can be used as filters.

    Parameter Data Type Filter Sort Expand Description
    bytes_in bigint Last sampled usage value received from net_device (running total since last device reset)
    bytes_out bigint Last sampled usage value received from net_device (running total since last device reset)
    cinr double Carrier to Interference plus Noise Ratio (dB)
    dbm int Strength of received signal (dBm)
    ecio int Ec/Io, the ratio of average channel power to total signal power (dB)
    id int Object ID
    net_device url =, __in net_device that reported the usage sample
    resource_url url Object URL
    rsrp double LTE reference signal receive power
    rsrq double LTE reference signal receive quality
    rssi int Received Signal Strength Indication (units vary with manufacturer)
    Note: Only for WiFi as WAN interfaces
    service_type string Last sampled service type value received from net_device
    signal_strength int Last sampled signal value received from net_device
    sinr double Signal to Interference plus Noise Ratio (dB)
    update_ts timestamp __gt, __lt Last time any field on this record was updated
    cell_id string Cell Tower ID
    mcc string Mobile Country Code (PLMN component)
    mnc string Mobile Network Code (PLMN component)
    lac string Location Area Code
    tac string Tracking Area Code

    Endpoint base path:

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

    IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
    Correct format:    https://www.cradlepointecm.com/api/v2/<endpoint name>/
    Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
  • Tips for Using the NetCloud API
  • When making API calls with curl in a console session, it can be helpful to define variables for your API keys, payloads, and the base URL of the endpoint for re-use with each curl statement.
    Please note that the method for setting variables in your console of choice can vary depending on the console/OS used. These variable definition examples are BASH specific; other console tools can require slightly different syntax to define these variables in a console session.

    • X_ECM_API_ID="<X-ECM-API-ID>"
    • X_ECM_API_KEY="<X-ECM-API-KEY>"
    • X_CP_API_ID="<X-CP-API-ID>"
    • X_CP_API_KEY="<X-CP-API-KEY>"
    • -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY"
    • URL="https://www.cradlepointecm.com/api/v2/net_device_metrics/"
    • BODY = -d '{"<field name>": "<field value>"}

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

  • GET Examples
  • Example curl GET request/response to the net_device_metrics endpoint without filters applied.

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/net_device_metrics/?net_device=134193"

    Response body for curl GET example

    {
        "data": [
            {
                "bytes_in": 1284122915,
                "bytes_out": 1274644165,
                "cinr": null,
                "dbm": null,
                "ecio": null,
                "id": "134193",
                "net_device": "https://www.cradlepointecm.com/api/v2/net_devices/134193/",
                "resource_url": "https://www.cradlepointecm.com/api/v2/net_device_metrics/134193/",
                "rsrp": null,
                "rsrq": null,
                "rssi": null,
                "service_type": "EVDO",
                "signal_strength": null,
                "sinr": null,
                "update_ts": "2015-12-30T06:40:20.306754+00:00"
            },
            {
               "bytes_in": 0,
               "bytes_out": 0,
               "cinr": null,
               "dbm": null,
               "ecio": null,
               "id": "134194",
               "net_device": "https://www.cradlepointecm.com/api/v2/net_devices/134194/",
               "resource_url": "https://www.cradlepointecm.com/api/v2/net_device_metrics/134194/",
               "rsrp": null,
               "rsrq": null,
               "rssi": null,
               "service_type": "EVDO",
               "signal_strength": 0,
               "sinr": null,
               "update_ts": "2015-12-30T06:40:20.323704+00:00"
            }
        ],
        "meta": {
            "limit": 20,
            "next": "https://www.cradlepointecm.com/api/v2/net_device_metrics/?limit=20&offset=20",
            "offset": 0,
            "previous": null
        }
    }
     

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.

Supported methods: GET.
  • net_device_signal_samples Endpoint Fields and Filters
  • This table lists the fields associated with the net_device_signal_samples endpoint. Fields with operators specified in the Filter column indicate that those fields can be used as filters.

    Parameter Data Type Filter Sort Expand Description
    cinr double Carrier to Interference plus Noise Ratio (dB)
    created_at timestamp __gt, __lt Time the sample was created
    created_at_timeuuid timeuuid =, __in, __gt, __gte, __lt, __lte A unique ID associated with the created_at timestamp. Ordering by the ID is equivalent to time ordering. This field can identify a specific record or be used for paging.
    dbm int Strength of received signal (dBm)
    ecio int Ec/Io, the ratio of average channel power to total signal power (dB)
    net_device url =, __in Network device that reported the usage sample
    rsrp double LTE reference signal receive power
    rsrp5g double 5G reference signal receive power
    rsrq double LTE reference signal receive quality
    rsrq5g double 5G reference signal receive quality
    rssi int Received Signal Strength Indication (units vary with manufacturer)
    Note: Only for WiFi as WAN interfaces
    signal_percent int Percent signal strength, derived heuristically from other values
    sinr double Signal to Interference plus Noise Ratio (dB)
    sinr5g double 5G Signal to Interference plus Noise Ratio (dB)
    uptime double Time in seconds since the net device established its link

    Endpoint base path:

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

    IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
    Correct format:    https://www.cradlepointecm.com/api/v2/<endpoint name>/
    Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
  • Tips for Using the NetCloud API
  • When making API calls with curl in a console session, it can be helpful to define variables for your API keys, payloads, and the base URL of the endpoint for re-use with each curl statement.
    Please note that the method for setting variables in your console of choice can vary depending on the console/OS used. These variable definition examples are BASH specific; other console tools can require slightly different syntax to define these variables in a console session.

    • X_ECM_API_ID="<X-ECM-API-ID>"
    • X_ECM_API_KEY="<X-ECM-API-KEY>"
    • X_CP_API_ID="<X-CP-API-ID>"
    • X_CP_API_KEY="<X-CP-API-KEY>"
    • -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY"
    • URL="https://www.cradlepointecm.com/api/v2/net_device_signal_samples/"
    • BODY = -d '{"<field name>": "<field value>"}

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

  • GET Examples
  • Example curl GET request/response to the net_device_signal_samples endpoint without filters applied.

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/net_device_signal_samples/"

    Response body for curl GET example

    {
        "data": [
            {
                "cinr": null,
                "created_at": "2015-08-12T09:29:34.093808",
                "created_at_timeuuid": "a473635e-40d4-11e5-b4b1-064520e3840d",
                "dbm": -59,
                "ecio": null,
                "net_device": "https://www.cradlepointecm.com/api/v2/net_devices/84730/",
                "rsrp": null,
                "rsrq": null,
                "rssi": null,
                "signal_percent": 39,
                "sinr": 6,
                "uptime": 80
            },
            { .... }
        ],
        "meta": {
            "limit": 20,
            "next": null,
            "previous": null
        }
    }
     

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.

Supported methods: GET.
  • net_device_usage_samples Endpoint Fields and Filters
  • This table lists the fields associated with the net_device_usage_samples endpoint. Fields with operators specified in the Filter column indicate that those fields can be used as filters.

    Parameter Data Type Filter Sort Expand Description
    bytes_in bigint Bytes received to device since last update
    bytes_out bigint Bytes sent from device since last update
    created_at timestamp __gt, __lt Time the sample was created
    created_at_timeuuid timeuuid =, __in, __gt, __gte, __lt, __lte A unique ID associated with the created_at timestamp. Ordering by the ID is equivalent to time ordering. This field can identify a specific record or be used for paging.
    net_device url =, __in Network device that reported the usage sample
    period double Time in seconds since the last sample was reported
    uptime double Time in seconds since the net device established its link

    Endpoint base path:

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

    IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
    Correct format:    https://www.cradlepointecm.com/api/v2/<endpoint name>/
    Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
  • Tips for Using the NetCloud API
  • When making API calls with curl in a console session, it can be helpful to define variables for your API keys, payloads, and the base URL of the endpoint for re-use with each curl statement.
    Please note that the method for setting variables in your console of choice can vary depending on the console/OS used. These variable definition examples are BASH specific; other console tools can require slightly different syntax to define these variables in a console session.

    • X_ECM_API_ID="<X-ECM-API-ID>"
    • X_ECM_API_KEY="<X-ECM-API-KEY>"
    • X_CP_API_ID="<X-CP-API-ID>"
    • X_CP_API_KEY="<X-CP-API-KEY>"
    • -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY"
    • URL="https://www.cradlepointecm.com/api/v2/net_device_usage_samples/"
    • BODY = -d '{"<field name>": "<field value>"}

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

  • GET Examples
  • Example curl GET request/response to the net_device_usage_samples endpoint without filters applied.

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/net_device_usage_samples/"

    Response body for curl GET example

    {
        "data": [
            {
                "bytes_in": 41055349,
                "bytes_out": 26513817,
                "created_at": "2021-02-09T22:37:08.009631+00:00",
                "created_at_timeuuid": "5774ba36-6b27-11eb-810a-82c571ff5873",
                "net_device": "https://www.cradlepointecm.com/api/v2/net_devices/74404917/",
                "period": 2766.1619693620014,
                "uptime": 193395.479387832
            },
            {
                "bytes_in": 523161,
                "bytes_out": 830563,
                "created_at": "2021-02-09T22:37:08.006812+00:00",
                "created_at_timeuuid": "57744c1a-6b27-11eb-9b8a-82c571ff5873",
                "net_device": "https://www.cradlepointecm.com/api/v2/net_devices/74404916/",
                "period": 1424.0312275589968,
                "uptime": 193395.479387832
            },
            ... 
            ],
            "meta": {
                "limit": 20,
                "next": "https://www.cradlepointecm.com/api/v2/net_device_usage_samples/?created_at_timeuuid__lt=06c75c2c-6b0b-11eb-975d-fa12fe283560"
            }
        }        
     

    Example curl GET request/response to the net_device_usage_samples endpoint with the created_at_timeuuid filter applied.

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/net_device_usage_samples/?created_at_timeuuid=f803740a-6b14-11eb-a773-12bfd7fde28d"

    Response body for curl GET example

    {
        "data": [
            {
                "bytes_in": 115192663,
                "bytes_out": 192047700,
                "created_at": "2021-02-09T20:25:36.942593+00:00",
                "created_at_timeuuid": "f803740a-6b14-11eb-a773-12bfd7fde28d",
                "net_device": "https://www.cradlepointecm.com/api/v2/net_devices/74404917/",
                "period": 2074.1544243349927,
                "uptime": 185504.796904274
            }
        ],
        "meta": {
            "limit": 20,
            "next": null
        }
    }
            

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.

Supported methods: GET.
  • net_devices Endpoint Fields and Filters
  • This table lists the fields associated with the net_devices endpoint. Fields with operators specified in the Filter column indicate that those fields can be used as filters.

    Parameter Data Type Filter Sort Expand Description
    account url =, __in Account that owns the object
    bsid string Base Station ID
    carrier string The connected carrier if available. Otherwise, the carrier the modem is configured to connect to
    carrier_id string The carrier the modem is currently registered with
    channel int WiFi channel currently in use, if applicable
    connection_state string =, __in Connected, Connecting, Disconnecting, Disconnected, Error, Ready, Configuring
    dns0 string Primary DNS server
    dns1 string Secondary DNS server
    esn string Electronic serial number
    gateway string Gateway server onto network
    gsn string Modem's global object identifier
    homecarrid string Modem's home carrier identifier
    hostname string Net device's hostname, if available
    iccid string Modem's SIM card's integrated circuit card identifier
    id int =, __in Object ID
    imei string Modem's international mobile station equipment identity number
    imsi string Modem's SIM card's unique subscriber identity
    ipv4_address string =, __in Device's IPv4 address
    is_asset boolean = True for modem net devices
    is_gps_supported boolean True if the device supports GPS
    is_upgrade_available boolean True if a new version of modem firmware is available
    is_upgrade_supported boolean True if the modem firmware is upgradable
    ltebandwidth string Indicates the frequency width of the LTE Band being used by the modem module
    mac string MAC address of the net device
    manufacturer string Manufacturer of the net device
    mdn string Modem's mobile data number (phone number)
    meid string Modem's CDMA unique identifier
    mfg_model string Network device's manufacturing model
    mfg_product string Product name of the net device
    mn_ha_spi string Mobile Node Home Agent Security Parameter Index - Indicates the specific security association between the home agent and the mobile device and the algorithm used for security purposes
    mn_ha_ss string Mobile Node Home Agent Shared Secret - Contains the shared secret used between the home agent and mobile device for security purposes
    mode string =, __in Net device's mode, WAN or LAN
    model string Net device's model
    model_fw string Modem's current firmware version
    mtu int Modem's network maximum transmission unit size
    nai string Modem's Network access identifier
    name string Network device's name, e.g. 'ethernet-wan', 'lte-1234abcd', 'mdm-dcba4321'
    netmask string Net device's netmask
    pin_status string Indicates the status of the SIM PIN. Examples include "READY", "PIN REQUIRED:, etc
    port string Port identifier on device
    prlv string Preferred Roaming List Version - Indicates the version of the Preferred Roaming List that is being used by the modem module
    profile string Indicates the active CDMA profile used by the modem module
    resource_url url Object URL
    rfband string Indicates the Radio Frequency Band that is currently being used by the modem module
    rfchannel string Indicates the Radio Frequency Channel that is currently being used by the modem module
    roam string Indicates if the modem is roaming outside its home network (0 - Roaming on a non-preferred network, 1 - Home network, 2 - Roaming on a preferred network)
    router url =, __in Cradlepoint device the net device is currently connected to
    rxchannel string Indicates the Radio Frequency Channel that is currently being used by for receiving data
    serial string Serial number of net device
    service_type string Connection mode: 3G, 4G, etc
    ssid string Service set identifier or network name
    summary string Additional net device state details, e.g. suspended, unconfigured, connecting, unplugged
    txchannel string Indicates the Radio Frequency Channel that is currently being used by for transmitting data
    type string Device type, e.g. 'mdm', 'modem', 'lte', 'ethernet'
    uid string A unique identifier used to the net device by the Cradlepoint device
    updated_at timestamp Time of last update to this object
    uptime float Time in seconds since the net device established its link
    ver_pkg string Indicates the firmware package version that is currently loaded on the modem module
    version string Firmware version of the network device
    wimax_realm string WiMAX realm string used to connect to a WiMAX network

    Endpoint base path:

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

    IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
    Correct format:    https://www.cradlepointecm.com/api/v2/<endpoint name>/
    Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
  • Tips for Using the NetCloud API
  • When making API calls with curl in a console session, it can be helpful to define variables for your API keys, payloads, and the base URL of the endpoint for re-use with each curl statement.
    Please note that the method for setting variables in your console of choice can vary depending on the console/OS used. These variable definition examples are BASH specific; other console tools can require slightly different syntax to define these variables in a console session.

    • X_ECM_API_ID="<X-ECM-API-ID>"
    • X_ECM_API_KEY="<X-ECM-API-KEY>"
    • X_CP_API_ID="<X-CP-API-ID>"
    • X_CP_API_KEY="<X-CP-API-KEY>"
    • -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY"
    • URL="https://www.cradlepointecm.com/api/v2/net_devices/"
    • BODY = -d '{"<field name>": "<field value>"}

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

  • GET Examples
  • Example curl GET request/response to the net_devices endpoint without filters applied.

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/net_devices/"

    Response body for curl GET example

      {
        "data": [
            {
                "account": "https://www.cradlepointecm.com/api/v2/accounts/<account number>/",
                "bsid": null,
                "carrier": "Unknown Service",
                "carrier_id": null,
                "channel": null,
                "connection_state": "unplugged",
                "dns0": null,
                "dns1": null,
                "esn": null,
                "gateway": null,
                "gsn": "353547063430048",
                "homecarrid": null,
                "hostname": "JGE-IBR900-f1d",
                "iccid": null,
                "id": "32081658",
                "imei": "353547063430048",
                "imsi": null,
                "ipv4_address": null,
                "is_asset": true,
                "is_gps_supported": true,
                "is_upgrade_available": false,
                "is_upgrade_supported": true,
                "ltebandwidth": null,
                "mac": null,
                "manufacturer": "Cradlepoint Inc.",
                "mdn": null,
                "meid": "35354706343004",
                "mfg_model": "MC7354-CP",
                "mfg_product": "Internal LPE (SIM1)",
                "mn_ha_spi": null,
                "mn_ha_ss": null,
                "mode": "wan",
                "model": "Internal LPE-VZ (SIM1)",
                "modem_fw": "Verizon Wireless",
                "mtu": 1428,
                "nai": null,
                "name": "mdm-c5be779",
                "netmask": null,
                "pin_status": "NOSIM",
                "port": "int1",
                "prlv": null,
                "profile": null,
                "resource_url": "https://www.cradlepointecm.com/api/v2/net_devices/32081658/",
                "rfband": null,
                "rfchannel": null,
                "roam": null,
                "router": null,
                "rxchannel": null,
                "serial": "353547063430048",
                "service_type": "Not Available",
                "ssid": null,
                "summary": "unplugged",
                "txchannel": null,
                "type": "mdm",
                "uid": "c5be779",
                "updated_at": "2018-12-12T16:41:31.117640+00:00",
                "uptime": null,
                "ver_pkg": "05.05.58.01_VZW,005.030_000",
                "version": "SWI9X15C_05.05.58.01 r27044 carmd-fwbuild1 2015/03/05 00:02:40",
                "wimax_realm": "sprintpcs.com"
            },
            ... 
        ],
        "meta": {
            "limit": 20,
            "next": null,
            "offset": 0,
            "previous": null
        }    
    }        
     

    Example curl GET request/response to the net_devices endpoint with the ID filter applied.

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/net_devices/?id=32081658"

    Response body for curl GET example

    {
        "data": [
            {
                "account": "https://www.cradlepointecm.com/api/v2/accounts/<account number>/",
                "bsid": null,
                "carrier": "Unknown Service",
                "carrier_id": null,
                "channel": null,
                "connection_state": "unplugged",
                "dns0": null,
                "dns1": null,
                "esn": null,
                "gateway": null,
                "gsn": "353547063430048",
                "homecarrid": null,
                "hostname": "JGE-IBR900-f1d",
                "iccid": null,
                "id": "32081658",
                "imei": "353547063430048",
                "imsi": null,
                "ipv4_address": null,
                "is_asset": true,
                "is_gps_supported": true,
                "is_upgrade_available": false,
                "is_upgrade_supported": true,
                "ltebandwidth": null,
                "mac": null,
                "manufacturer": "Cradlepoint Inc.",
                "mdn": null,
                "meid": "35354706343004",
                "mfg_model": "MC7354-CP",
                "mfg_product": "Internal LPE (SIM1)",
                "mn_ha_spi": null,
                "mn_ha_ss": null,
                "mode": "wan",
                "model": "Internal LPE-VZ (SIM1)",
                "modem_fw": "Verizon Wireless",
                "mtu": 1428,
                "nai": null,
                "name": "mdm-c5be779",
                "netmask": null,
                "pin_status": "NOSIM",
                "port": "int1",
                "prlv": null,
                "profile": null,
                "resource_url": "https://www.cradlepointecm.com/api/v2/net_devices/32081658/",
                "rfband": null,
                "rfchannel": null,
                "roam": null,
                "router": null,
                "rxchannel": null,
                "serial": "353547063430048",
                "service_type": "Not Available",
                "ssid": null,
                "summary": "unplugged",
                "txchannel": null,
                "type": "mdm",
                "uid": "c5be779",
                "updated_at": "2018-12-12T16:41:31.117640+00:00",
                "uptime": null,
                "ver_pkg": "05.05.58.01_VZW,005.030_000",
                "version": "SWI9X15C_05.05.58.01 r27044 carmd-fwbuild1 2015/03/05 00:02:40",
                "wimax_realm": "sprintpcs.com"
            }
        ],
        "meta": {
            "limit": 20,
            "next": null,
            "offset": 0,
            "previous": null
        }
    }

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 overlay_network_bindings endpoint to retrieve information about NCP Gateway Clients, such as gateway_id and state. Also used to install NCP Gateway client on a device and bind it to a network. This endpoint can be used with the router_lans and forwarding_lan_details endpoints to deploy a NetCloud Perimeter Gateway on a device. See the Create a NetCloud Perimter Gateway section below for more information.

Supported methods: GET, POST, PUT, DELETE.
  • overlay_network_bindings Endpoint Fields and Filters
  • This table lists the fields associated with the overlay_network_bindings endpoint. Fields with operators specified in the Filter column indicate that those fields can be used as filters.

    Parameter Data Type Filter Sort Expand Description Permissions
    account url =, __in Account that owns the overlay_network_bindings record Read/Write
    auto_whitelist boolean Auto whitelist status Read/Write
    created_at datetime Datetime the overlay_network_bindings record was created Read
    forwarding_lans url LANs where traffic is forwarded Read/Write
    forwarding_lan_details url =, __in Forwarding LAN details (enabled, auto-whitelist, lan) Read/Write
    gateway_id int =, __in ID of the associated gateway Read/Write
    group url =, __in Group url Read/Write
    id* int =, __in ID of the overlay_network_bindings record Read
    refresh_pending boolean Refresh status Read/Write
    router url =, __in Router url Read/Write
    state string General state description Read/Write
    state_details string Detailed state description Read/Write
    updated_at datetime Datetime of the last update to the overlay_network_bindings record Read
    Note: * indicates the attribute is required for PUT and DELETE requests.

    Endpoint base path:

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

    IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
    Correct format:    https://www.cradlepointecm.com/api/v2/<endpoint name>/
    Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
  • Tips for Using the NetCloud API
  • When making API calls with curl in a console session, it can be helpful to define variables for your API keys, payloads, and the base URL of the endpoint for re-use with each curl statement.
    Please note that the method for setting variables in your console of choice can vary depending on the console/OS used. These variable definition examples are BASH specific; other console tools can require slightly different syntax to define these variables in a console session.

    • X_ECM_API_ID="<X-ECM-API-ID>"
    • X_ECM_API_KEY="<X-ECM-API-KEY>"
    • X_CP_API_ID="<X-CP-API-ID>"
    • X_CP_API_KEY="<X-CP-API-KEY>"
    • -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY"
    • URL="https://www.cradlepointecm.com/api/v2/overlay_network_bindings/"
    • BODY = -d '{"<field name>": "<field value>"}

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

  • Create a NetCloud Perimeter Gateway
  • Use the following steps to install the NetCloud Perimeter (NCP) Gateway Client on a device using the NetCloud API.

    1. Send a GET request to the router_lans endpoint and filter by router ID. Collect the router_lans IDs.
    2. Send a GET request to the forwarding_lan_details endpoint and filter by the previously collected router_lans IDs. Collect the forwarding_lan_details IDs.
    3. Use router_lans IDS and forwarding_lans_details IDs collected in the previous steps in the body of a POST request to overlay_network_bindings. This installs the NCP Gateway Client and binds it to an NCP network.

    1. GET request example to the router_lans endpoint to get the router_lans ID(s)

    curl -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/router_lans/2222/"
        

    Response example. Note the "id" field value (2222).

    {
        "data": [
            {
                "account": "https://www.cradlepointecm.com/api/v2/accounts/",
                "created_at": "2019-04-12T14:28:38.423098+00:00",
                "enabled": true,
                "id": "2222",
                "ip_address": "192.168.17.1",
                "name": "Primary LAN",
                "netmask": "255.255.255.0",
                "resource_url": "https://www.cradlepointecm.com/api/v2/router_lans/2222/",
                "router": "https://www.cradlepointecm.com/api/v2/routers/12345/",
                "updated_at": "2020-12-21T00:22:56.363885+00:00"
            },
            {
                "meta": {
                    "limit": 20,
                    "next": null,
                    "offset": 0,
                    "previous": null
                }
            }
        ]
    }
        

    2. GET request example to the forwarding_lan_details endpoint to get the forwarding_lan_details ID(s).

    curl -X -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" -H "Content-Type: application/json" "https://www.cradlepointecm.com/api/v2/forwarding_lan_details/3333/"
      

    Response example. Note the "id" field value (3333).

    {
        "data": [
            {
                "auto_whitelist": false,
                "enabled": false,
                "id": "3333",
                "lan": "https://www.cradlepointecm.com/api/v2/router_lans/4444/",
                "network_id": null,
                "overlay_network_binding": null,
                "resource_url": "https://www.cradlepointecm.com/api/v2/forwarding_lan_details/3333/"
            },
            {
                "meta": {
                    "limit": 20,
                    "next": null,
                    "offset": 0,
                    "previous": null
                }
            }
        ]
    }
        

    3. POST request to overlay_network_bindings to create the NCP Gateway Client

    curl -H -x POST "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" -H "Content-Type: application/json" 
    -d '{
        "account": "https://www.cradlepointecm.com/api/v2/accounts/1111/",
        "router": "https://www.cradlepointecm.com/api/v2/routers/12345/",
        "network_id": 3333,
        "forwarding_lan_details": [
            {
                "enabled": true,
                "auto_whitelist": false,
                "lan": "https://www.cradlepointecm.com/api/v2/router_lans/4444/"
            },
            {
                "enabled": true,
                "auto_whitelist": false,
                "lan": "https://www.cradlepointecm.com/api/v2/router_lans/4444/"
            }
        ]
    }'
    "https://www.cradlepointecm.com/api/v2/overlay_network_bindings/"
        
  • GET Examples
  • Example curl GET request/response to the overlay_network_bindings endpoint without filters applied.

    curl -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/overlay_network_bindings/"
    

    Response body for curl GET example

    {
        "data": [
            {
                "account": "https://www.cradlepointecm.com/api/v2/accounts/<account number>/",
                "auto_whitelist": true,
                "created_at": "2020-02-27T20:45:49.322726+00:00",
                "forwarding_lan_details": "https://www.cradlepointecm.com/api/v2/overlay_network_bindings/35167/forwarding_lan_details/",
                "forwarding_lans": "https://www.cradlepointecm.com/api/v2/overlay_network_bindings/35167/forwarding_lans/",
                "gateway_id": 244184,
                "group": "https://www.cradlepointecm.com/api/v2/groups/None/",
                "id": "35167",
                "network_id": 37841,
                "refresh_pending": false,
                "resource_url": "https://www.cradlepointecm.com/api/v2/overlay_network_bindings/35167/",
                "router": "https://www.cradlepointecm.com/api/v2/routers/1284575/",
                "state": "OK",
                "state_details": "ACTIVE",
                "updated_at": "2021-02-19T11:23:55.125217+00:00"
            },
            {
                "account": "https://www.cradlepointecm.com/api/v2/accounts/<account number>/",
                "auto_whitelist": true,
                "created_at": "2020-11-18T17:06:38.928021+00:00",
                "forwarding_lan_details": "https://www.cradlepointecm.com/api/v2/overlay_network_bindings/43453/forwarding_lan_details/",
                "forwarding_lans": "https://www.cradlepointecm.com/api/v2/overlay_network_bindings/43453/forwarding_lans/",
                "gateway_id": 342430,
                "group": "https://www.cradlepointecm.com/api/v2/groups/None/",
                "id": "43453",
                "network_id": 37841,
                "refresh_pending": false,
                "resource_url": "https://www.cradlepointecm.com/api/v2/overlay_network_bindings/43453/",
                "router": "https://www.cradlepointecm.com/api/v2/routers/2174016/",
                "state": "OK",
                "state_details": "ACTIVE",
                "updated_at": "2021-02-21T10:02:00.588354+00:00"
            }
        ],
        "meta": {
            "limit": 20,
            "next": null,
            "offset": 0,
            "previous": null
        }
    }
     
  • POST Examples
  • Example curl POST request/response to the overlay_network_bindings endpoint..

    curl -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" -H "Content-Type: application/json" -d '{"auto_whitelist":false, "refresh_pending": false, "created_at": "2021-01-27T01:03:02.527774+00:00","updated_at": "2021-01-27T01:03:02.527774+00:00", "account":"https://www.cradlepointecm.com/api/v2/accounts/3/", "router": "https://www.cradlepointecm.com/api/v2/routers/3/", "network_id": 12345 }' "https://www.cradlepointecm.com/api/v2/overlay_network_bindings/"
        

    Response body for curl POST example

    {
        "account": "https://www.cradlepointecm.com/api/v2/accounts/3/",
        "auto_whitelist": false,
        "created_at": "2021-01-27T22:11:20.328722+00:00",
        "forwarding_lan_details": "https://www.cradlepointecm.com/api/v2/overlay_network_bindings/8/forwarding_lan_details/",
        "forwarding_lans": "https://www.cradlepointecm.com/api/v2/overlay_network_bindings/8/forwarding_lans/",
        "gateway_id": null,
        "group": "https://www.cradlepointecm.com/api/v2/groups/None/",
        "id": "8",
        "network_id": 31682,
        "refresh_pending": false,
        "resource_url": "https://www.cradlepointecm.com/api/v2/overlay_network_bindings/",
        "router": "https://www.cradlepointecm.com/api/v2/routers/3/",
        "state": null,
        "state_details": null,
        "updated_at": "2021-01-27T22:11:20.328746+00:00"
    }
        
  • PUT Examples
  • Example curl PUT request/response to the overlay_network_bindings endpoint. This updates the auto_whitelist field to 'true' for the specified record.

    curl -X PUT -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" -H "Content-Type: application/json" -d '{"auto_whitelist":true}' "https://www.cradlepointecm.com/api/v2/overlay_network_bindings/1/"

    Response body for curl PUT example

            
    {
        "data": [
            {
                "account": "https://www.cradlepointecm.com/api/v2/accounts/3/",
                "auto_whitelist": true,
                "created_at": "2021-01-27T05:08:20.686925+00:00",
                "forwarding_lan_details": "https://www.cradlepointecm.com/api/v2/overlay_network_bindings/1/forwarding_lan_details/",
                "forwarding_lans": "https://www.cradlepointecm.com/api/v2/overlay_network_bindings/1/forwarding_lans/",
                "gateway_id": 132997,
                "group": "https://www.cradlepointecm.com/api/v2/groups/None/",
                "id": "1",
                "network_id": 12345,
                "refresh_pending": false,
                "resource_url": "https://www.cradlepointecm.com/api/v2/overlay_network_bindings/1/",
                "router": "https://www.cradlepointecm.com/api/v2/routers/3/",
                "state": null,
                "state_details": null,
                "updated_at": "2021-01-27T05:11:07.550503+00:00"
            }
        ],
        "meta": {
            "limit": 20,
            "next": null,
            "offset": 0,
            "previous": null
        }
    }
    
  • DELETE Example
  • Example curl DELETE request/response to the overlay_network_bindings endpoint.

    curl -X DELETE -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "$NCM/api/v2/overlay_network_bindings/1/"

    Successful DELETE actions return a 204 response with no content in the body.

Forms

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

Supported methods: GET.
  • products Endpoint Fields and Filters
  • This table lists the fields associated with the products endpoint. Fields with operators specified in the Filter column indicate that those fields can be used as filters.

    Parameter Data Type Filter Sort Expand Description
    device_type string =, __in Type of device, e.g. router or access point
    id int =, __in ID of a products record object
    name string Name of the product, e.g. IBR600
    resource_url url URL for a products object
    series int Series of the product, e.g. 2 or 3

    Endpoint base path:

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

    IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
    Correct format:    https://www.cradlepointecm.com/api/v2/<endpoint name>/
    Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
  • Tips for Using the NetCloud API
  • When making API calls with curl in a console session, it can be helpful to define variables for your API keys, payloads, and the base URL of the endpoint for re-use with each curl statement.
    Please note that the method for setting variables in your console of choice can vary depending on the console/OS used. These variable definition examples are BASH specific; other console tools can require slightly different syntax to define these variables in a console session.

    • X_ECM_API_ID="<X-ECM-API-ID>"
    • X_ECM_API_KEY="<X-ECM-API-KEY>"
    • X_CP_API_ID="<X-CP-API-ID>"
    • X_CP_API_KEY="<X-CP-API-KEY>"
    • -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY"
    • URL="https://www.cradlepointecm.com/api/v2/products/"
    • BODY = -d '{"<field name>": "<field value>"}

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

  • GET Examples
  • Example curl GET request/response to the products endpoint without filters applied.

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/products/"

    Response body for curl GET example

    {
        "data": [
            {
                "device_type": "router",
                "id": "1",
                "name": "MBR1400",
                "resource_url": "https://www.cradlepointecm.com/api/v2/products/1/",
                "series": 3
            },
            {
                "device_type": "router",
                "id": "2",
                "name": "MBR1400v2",
                "resource_url": "https://www.cradlepointecm.com/api/v2/products/2/",
                "series": 3
            },
            {
                "device_type": "router",
                "id": "3",
                "name": "CBR400",
                "resource_url": "https://www.cradlepointecm.com/api/v2/products/3/",
                "series": 3
            },
            {
                "device_type": "router",
                "id": "4",
                "name": "CBR450",
                "resource_url": "https://www.cradlepointecm.com/api/v2/products/4/",
                "series": 3
            },
    ...
        ],
        "meta": {
            "limit": 20,
            "next": "https://www.cradlepointecm.com/api/v2/products/?limit=20&offset=20",
            "offset": 0,
            "previous": null
        }
    }
     

    Example curl GET request/response to the products endpoint with the ID filter applied. This retrieves the product matching the ID "29".

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/products/?id=29"

    Response body for curl GET example

    {
        "data": [
            {
                "device_type": "router",
                "id": "29",
                "name": "AER3150",
                "resource_url": "https://www.cradlepointecm.com/api/v2/products/29/",
                "series": 3
            }
        ],
        "meta": {
            "limit": 20,
            "next": null,
            "offset": 0,
            "previous": null
        }
    }

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
  • Example curl POST request to the reboot_activity endpoint. This reboots a router with the ID "42".

    curl -v -X POST -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" -H "Content-Type:application/json" "https://www.cradlepointecm.com/api/v2/reboot_activity/" -d '{"router":"https://www.cradlepointecm.com/api/v2/routers/42/"}'
          

    Example curl POST request to the reboot_activity endpoint. This reboots the routers in the group with the ID "24".

    curl -v -X POST -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" -H "Content-Type:application/json" "https://www.cradlepointecm.com/api/v2/reboot_activity/" -d '{"group":"https://www.cradlepointecm.com/api/v2/groups/24/"}'
           

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.

  • router_alerts Endpoint Fields and Filters
  • This table lists the fields associated with the router_alerts endpoint. Fields with operators specified in the Filter column indicate that those fields can be used as filters.

    Parameter Data Type Filter Sort Expand Description
    created_at timestamp __gt, __lt Time the alert record was created in NCM
    created_at_timeuuid timeuuid =, __in, __gt, __gte, __lt, __lte A unique ID associated with the created_at timestamp. Ordering by the ID is equivalent to time ordering. This field can identify a specific record or be used for paging.
    detected_at timestamp Time the alert was detected
    friendly_info string Human-readable description of the alert
    info json Alert-type specific information
    router url =, __in Device this alert is related to
    type string The type of the alert

    Endpoint base path:

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

    IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
    Correct format:    https://www.cradlepointecm.com/api/v2/<endpoint name>/
    Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
  • Tips for Using the NetCloud API
  • When making API calls with curl in a console session, it can be helpful to define variables for your API keys, payloads, and the base URL of the endpoint for re-use with each curl statement.
    Please note that the method for setting variables in your console of choice can vary depending on the console/OS used. These variable definition examples are BASH specific; other console tools can require slightly different syntax to define these variables in a console session.

    • X_ECM_API_ID="<X-ECM-API-ID>"
    • X_ECM_API_KEY="<X-ECM-API-KEY>"
    • X_CP_API_ID="<X-CP-API-ID>"
    • X_CP_API_KEY="<X-CP-API-KEY>"
    • -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY"
    • URL="https://www.cradlepointecm.com/api/v2/router_alerts/"
    • BODY = -d '{"<field name>": "<field value>"}

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

  • GET Examples
  • Example curl GET request/response to the router_alerts endpoint without filters applied.

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/router_alerts/"

    Response body for curl GET example

    {
        "data": [
            {
                "created_at": "2020-12-07T17:44:19.430235+00:00",
                "created_at_timeuuid": "d554418c-38b3-11eb-acd7-32b969db3e3f",
                "detected_at": "2020-12-07T17:44:18.145000+00:00",
                "friendly_info": "User admin has logged into the router from 127.0.0.1.",
                "info": {
                    "ip": "127.0.0.1",
                    "time": [
                        "2020-12-07 17:44:18",
                        "UTC"
                    ],
                    "type": "login_success",
                    "user": "admin"
                },
                "router": "https://www.cradlepointecm.com/api/v2/routers/2162719/",
                "type": "login_success"
            },
            {
                "created_at": "2020-12-04T09:20:30.538148+00:00",
                "created_at_timeuuid": "f4442066-3611-11eb-bd86-5ebca3547463",
                "detected_at": "2020-12-04T09:16:16.405000+00:00",
                "friendly_info": "The ethernet port \"Ethernet\" has connected to the network.",
                "info": {
                    "alert_type": "ethernet_wan_connected",
                    "history": [],
                    "info": {
                        "mac": "00:30:44:47:cb:09",
                        "port": "Ethernet",
                        "raw_port": "eth0",
                        "reason": "Manual",
                        "type": "ethernet",
                        "uid": "wan"
                    },
                    "status": "connected",
                    "time": [
                        "2020-12-04 09:16:16",
                        "UTC"
                    ],
                    "type": "wan_status_change"
                },
                "router": "https://www.cradlepointecm.com/api/v2/routers/2162719/",
                "type": "ethernet_wan_connected"
            },
            ... 
    ],
    "meta": {
            "limit": 20,
            "next": null
            }
        }
     

    Example curl GET request/response to the router_alerts endpoint with the created_at_timeuuid filter applied.

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/router_alerts/?created_at_timeuuid=f4442066-3611-11eb-bd86-5ebca3547463"

    Response body for curl GET example

    {
                "data": [
                    {
                        "created_at": "2020-12-04T09:20:30.538148+00:00",
                        "created_at_timeuuid": "f4442066-3611-11eb-bd86-5ebca3547463",
                        "detected_at": "2020-12-04T09:16:16.405000+00:00",
                        "friendly_info": "The ethernet port \"Ethernet\" has connected to the network.",
                        "info": {
                            "alert_type": "ethernet_wan_connected",
                            "history": [],
                            "info": {
                                "mac": "00:30:44:47:cb:09",
                                "port": "Ethernet",
                                "raw_port": "eth0",
                                "reason": "Manual",
                                "type": "ethernet",
                                "uid": "wan"
                            },
                            "status": "connected",
                            "time": [
                                "2020-12-04 09:16:16",
                                "UTC"
                            ],
                            "type": "wan_status_change"
                        },
                        "router": "https://www.cradlepointecm.com/api/v2/routers/2162719/",
                        "type": "ethernet_wan_connected"
                    }
                ],
                "meta": {
                    "limit": 20,
                    "next": null
                }
            }

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 address and netmask. This endpoint can be used with the forwarding_lan_details and overlay_network_bindings endpoints to deploy a NetCloud Perimeter Gateway on a device. See the Create a NetCloud Perimter Gateway section below for more information.

Supported methods: GET.
  • router_lans Endpoint Fields and Filters
  • This table lists the fields associated with the router_lans endpoint. Fields with operators specified in the Filter column indicate that those fields can be used as filters.

    Parameter Data Type Filter Sort Expand Description
    account int =, __in Account that owns the router_lans record
    created_at datetime Datetime the router_lans record was created
    enabled boolean Enabled/disabled state of a router_lans record
    id int =, __in ID of the router_lans record
    ip_address string =, __in IP address
    name string =, __in Name of the router_lans record
    netmask url Netmask for the lan
    router int =, __in Router ID
    updated_at datetime Datetime of the last update to the router_lans record

    Endpoint base path:

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

    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>
  • Tips for Using the NetCloud API
  • When making API calls with curl in a console session, it can be helpful to define variables for your API keys, payloads, and the base URL of the endpoint for re-use with each curl statement.
    Please note that the method for setting variables in your console of choice can vary depending on the console/OS used. These variable definition examples are BASH specific; other console tools can require slightly different syntax to define these variables in a console session.

    • X_ECM_API_ID="<X-ECM-API-ID>"
    • X_ECM_API_KEY="<X-ECM-API-KEY>"
    • X_CP_API_ID="<X-CP-API-ID>"
    • X_CP_API_KEY="<X-CP-API-KEY>"
    • -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY"
    • URL="https://www.cradlepointecm.com/api/v2/router_lans/"
    • BODY = -d '{"<field name>": "<field value>"}

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

  • Create a NetCloud Perimeter Gateway
  • Use the following steps to install the NetCloud Perimeter (NCP) Gateway Client on a device using the NetCloud API.

    1. Send a GET request to the router_lans endpoint and filter by router ID. Collect the router_lans IDs.
    2. Send a GET request to the forwarding_lan_details endpoint and filter by the previously collected router_lans IDs. Collect the forwarding_lan_details IDs.
    3. Use router_lans IDS and forwarding_lans_details IDs collected in the previous steps in the body of a POST request to overlay_network_bindings. This installs the NCP Gateway Client and binds it to an NCP network.

    1. GET request example to the router_lans endpoint to get the router_lans ID(s)

    curl -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/router_lans/2222/"
        

    Response example. Note the "id" field value (2222).

    {
        "data": [
            {
                "account": "https://www.cradlepointecm.com/api/v2/accounts/",
                "created_at": "2019-04-12T14:28:38.423098+00:00",
                "enabled": true,
                "id": "2222",
                "ip_address": "192.168.17.1",
                "name": "Primary LAN",
                "netmask": "255.255.255.0",
                "resource_url": "https://www.cradlepointecm.com/api/v2/router_lans/2222/",
                "router": "https://www.cradlepointecm.com/api/v2/routers/12345/",
                "updated_at": "2020-12-21T00:22:56.363885+00:00"
            },
            {
                "meta": {
                    "limit": 20,
                    "next": null,
                    "offset": 0,
                    "previous": null
                }
            }
        ]
    }
        

    2. GET request example to the forwarding_lan_details endpoint to get the forwarding_lan_details ID(s).

    curl -X -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" -H "Content-Type: application/json" "https://www.cradlepointecm.com/api/v2/forwarding_lan_details/3333/"
      

    Response example. Note the "id" field value (3333).

    {
        "data": [
            {
                "auto_whitelist": false,
                "enabled": false,
                "id": "3333",
                "lan": "https://www.cradlepointecm.com/api/v2/router_lans/4444/",
                "network_id": null,
                "overlay_network_binding": null,
                "resource_url": "https://www.cradlepointecm.com/api/v2/forwarding_lan_details/3333/"
            },
            {
                "meta": {
                    "limit": 20,
                    "next": null,
                    "offset": 0,
                    "previous": null
                }
            }
        ]
    }
        

    3. POST request to overlay_network_bindings to create the NCP Gateway Client

    curl -H -x POST "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" -H "Content-Type: application/json" 
    -d '{
        "account": "https://www.cradlepointecm.com/api/v2/accounts/1111/",
        "router": "https://www.cradlepointecm.com/api/v2/routers/12345/",
        "network_id": 3333,
        "forwarding_lan_details": [
            {
                "enabled": true,
                "auto_whitelist": false,
                "lan": "https://www.cradlepointecm.com/api/v2/router_lans/4444/"
            },
            {
                "enabled": true,
                "auto_whitelist": false,
                "lan": "https://www.cradlepointecm.com/api/v2/router_lans/4444/"
            }
        ]
    }'
    "https://www.cradlepointecm.com/api/v2/overlay_network_bindings/"
        
  • GET Examples
  • Example curl GET request/response to the router_lans endpoint without filters applied.

    curl -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/router_lans/"
    

    Response body for curl GET example

    {
        "data": [
            {
                "account": "https://www.cradlepointecm.com/api/v2/accounts//",
                "created_at": "2019-04-12T14:28:38.423098+00:00",
                "enabled": true,
                "id": "2147873",
                "ip_address": "192.168.17.1",
                "name": "Primary LAN",
                "netmask": "255.255.255.0",
                "resource_url": "https://www.cradlepointecm.com/api/v2/router_lans/2147873/",
                "router": "https://www.cradlepointecm.com/api/v2/routers/1284575/",
                "updated_at": "2020-12-21T00:22:56.363885+00:00"
            },
            {
                "account": "https://www.cradlepointecm.com/api/v2/accounts//",
                "created_at": "2020-11-18T17:06:23.672117+00:00",
                "enabled": true,
                "id": "3999183",
                "ip_address": "192.168.0.1",
                "name": "Primary LAN",
                "netmask": "255.255.255.0",
                "resource_url": "https://www.cradlepointecm.com/api/v2/router_lans/3999183/",
                "router": "https://www.cradlepointecm.com/api/v2/routers/2174016/",
                "updated_at": "2021-02-21T10:01:33.093821+00:00"
            },
            {
                "account": "https://www.cradlepointecm.com/api/v2/accounts//",
                "created_at": "2020-11-18T17:06:23.687020+00:00",
                "enabled": false,
                "id": "3999184",
                "ip_address": "192.168.11.1",
                "name": "Guest LAN",
                "netmask": "255.255.255.0",
                "resource_url": "https://www.cradlepointecm.com/api/v2/router_lans/3999184/",
                "router": "https://www.cradlepointecm.com/api/v2/routers/2174016/",
                "updated_at": "2021-02-21T10:01:33.101744+00:00"
            }
        ],
        "meta": {
            "limit": 20,
            "next": null,
            "offset": 0,
            "previous": null
        }
    }
     

    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.

Supported methods: GET.
  • router_logs Endpoint Fields and Filters
  • This table lists the fields associated with the router_logs endpoint. Fields with operators specified in the Filter column indicate that those fields can be used as filters.

    Parameter Data Type Filter Sort Expand Description
    created_at timestamp __gt, __lt Time the log entry was created in NCM
    created_at_timeuuid timeuuid =, __in, __gt, __gte, __lt, __lte A unique ID associated with the created_at timestamp. Ordering by the ID is equivalent to time ordering. This field can identify a specific record or be used for paging.
    exception string Contains details of a device exception (optional)
    level string The level of the log, e.g. DEBUG, INFO, WARNING, ERROR, CRITICAL
    message string The log message
    reported_at timestamp Time the log entry was written to the device's log
    router url = Device this log is related to
    sequence int The insertion order for each log events
    source string The source of the log entry

    Endpoint base path:

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

    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>
  • Tips for Using the NetCloud API
  • When making API calls with curl in a console session, it can be helpful to define variables for your API keys, payloads, and the base URL of the endpoint for re-use with each curl statement.
    Please note that the method for setting variables in your console of choice can vary depending on the console/OS used. These variable definition examples are BASH specific; other console tools can require slightly different syntax to define these variables in a console session.

    • X_ECM_API_ID="<X-ECM-API-ID>"
    • X_ECM_API_KEY="<X-ECM-API-KEY>"
    • X_CP_API_ID="<X-CP-API-ID>"
    • X_CP_API_KEY="<X-CP-API-KEY>"
    • -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY"
    • URL="https://www.cradlepointecm.com/api/v2/router_logs/"
    • BODY = -d '{"<field name>": "<field value>"}

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

  • GET Examples
  • Example curl GET request/response to the router_logs endpoint with the ??? filter applied. This retrieves

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/router_logs/?router=2162719"

    Response body for curl GET example

    {
        "data": [
            {
                "created_at": "2021-02-09T22:37:07.590858+00:00",
                "created_at_timeuuid": "2021-02-09T22:37:07.590858_0",
                "exception": null,
                "level": "INFO",
                "message": "Checking upgrade server for pkg: 24.01.521_Verizon,2013, fw_info path: ['status', 'wan', 'devices', 'mdm-11eec444e', 'ob_upgrade', 'fw_info_verizon']",
                "reported_at": "2021-02-09T17:05:12+00:00",
                "router": "https://www.cradlepointecm.com/api/v1/routers/2162719/",
                "sequence": 0,
                "source": "upgrade"
            },
            {
                "created_at": "2021-02-09T22:37:07.590858+00:00",
                "created_at_timeuuid": "2021-02-09T22:37:07.590858_1",
                "exception": null,
                "level": "INFO",
                "message": "Found file on server; version: 24.01.546_ATT,4028",
                "reported_at": "2021-02-09T17:05:12+00:00",
                "router": "https://www.cradlepointecm.com/api/v1/routers/2162719/",
                "sequence": 1,
                "source": "upgrade"
            },
            ...
        ],
        "meta": {
            "count": 20,
            "limit": 20,
            "next": "https://www.cradlepointecm.com/api/v2/router_logs/?router=2162719&limit=20&offset=20",
            "offset": 0,
            "previous": null
        }
    }
                

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.

Supported methods: GET.
  • router_state_samples Endpoint Fields and Filters
  • This table lists the fields associated with the router_state_samples endpoint. Fields with operators specified in the Filter column indicate that those fields can be used as filters.

    Parameter Data Type Filter Sort Expand Description
    created_at timestamp __gt, __lt Time the sample was created
    created_at_timeuuid timeuuid =, __in, __gt, __gte, __lt, __lte A unique ID associated with the created_at timestamp. Ordering by the ID is equivalent to time ordering. This field can identify a specific record or be used for paging.
    period double The time in seconds that the device was in this state
    router url =, __in Device that is connected to NCM
    state string The state of the device during this sample's period, e.g. online or offline

    Endpoint base path:

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

    IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
    Correct format:    https://www.cradlepointecm.com/api/v2/<endpoint name>/
    Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
  • Tips for Using the NetCloud API
  • When making API calls with curl in a console session, it can be helpful to define variables for your API keys, payloads, and the base URL of the endpoint for re-use with each curl statement.
    Please note that the method for setting variables in your console of choice can vary depending on the console/OS used. These variable definition examples are BASH specific; other console tools can require slightly different syntax to define these variables in a console session.

    • X_ECM_API_ID="<X-ECM-API-ID>"
    • X_ECM_API_KEY="<X-ECM-API-KEY>"
    • X_CP_API_ID="<X-CP-API-ID>"
    • X_CP_API_KEY="<X-CP-API-KEY>"
    • -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY"
    • URL="https://www.cradlepointecm.com/api/v2/router_state_samples/"
    • BODY = -d '{"<field name>": "<field value>"}

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

  • GET Examples
  • Example curl GET request/response to the router_state_samples endpoint without filters applied.

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/router_state_samples/"

    Response body for curl GET example

    {
        "data": [
            {
                "created_at": "2020-12-04T09:20:24.040723+00:00",
                "created_at_timeuuid": "f064b2c0-3611-11eb-9034-32d40d962d51",
                "period": 222.93943309783936,
                "router": "https://www.cradlepointecm.com/api/v2/routers/2162719/",
                "state": "offline"
            },
            {
                "created_at": "2020-12-04T09:18:42.592802+00:00",
                "created_at_timeuuid": "b3ecf954-3611-11eb-acf6-3a257258b42e",
                "period": 25334.473613977432,
                "router": "https://www.cradlepointecm.com/api/v2/routers/2162719/",
                "state": "online"
            },
            ... 
        ]
    }
     

    Example curl GET request/response to the router_state_samples endpoint with the created_at_timeuuid filter applied.

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/router_state_samples/?created_at_timeuuid=f221d310-3243-11eb-827b-daedcb174526"

    Response body for curl GET example

    {
        "data": [
            {
                "created_at": "2020-11-29T13:08:17.143272+00:00",
                "created_at_timeuuid": "f221d310-3243-11eb-827b-daedcb174526",
                "period": 188.75138449668884,
                "router": "https://www.cradlepointecm.com/api/v2/routers/2162719/",
                "state": "offline"
            }
        ],
        "meta": {
            "limit": 20,
            "next": null
        }
    }
            

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.

Supported methods: GET.
  • router_stream_usage_samples Endpoint Fields and Filters
  • This table lists the fields associated with the router_stream_usage_samples endpoint. Fields with operators specified in the Filter column indicate that those fields can be used as filters.

    Parameter Data Type Filter Sort Expand Description
    bytes_in bigint Bytes received by the device from NCM since last update
    bytes_out bigint Bytes sent from the device to NCM since last update
    created_at timestamp __gt, __lt Time the sample was created
    created_at_timeuuid timeuuid =, __in, __gt, __gte, __lt, __lte A unique ID associated with the created_at timestamp. Ordering by the ID is equivalent to time ordering. This field can identify a specific record or be used for paging.
    period double Time in seconds since the last sample was reported
    router url =, __in Device that is connected to NCM
    uptime double Time in seconds since the net device established its link

    Endpoint base path:

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

    IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
    Correct format:    https://www.cradlepointecm.com/api/v2/<endpoint name>/
    Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
  • Tips for Using the NetCloud API
  • When making API calls with curl in a console session, it can be helpful to define variables for your API keys, payloads, and the base URL of the endpoint for re-use with each curl statement.
    Please note that the method for setting variables in your console of choice can vary depending on the console/OS used. These variable definition examples are BASH specific; other console tools can require slightly different syntax to define these variables in a console session.

    • X_ECM_API_ID="<X-ECM-API-ID>"
    • X_ECM_API_KEY="<X-ECM-API-KEY>"
    • X_CP_API_ID="<X-CP-API-ID>"
    • X_CP_API_KEY="<X-CP-API-KEY>"
    • -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY"
    • URL="https://www.cradlepointecm.com/api/v2/router_stream_usage_samples/"
    • BODY = -d '{"<field name>": "<field value>"}

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

  • GET Examples
  • Example curl GET request/response to the router_stream_usage_samples endpoint without filters applied.

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/router_stream_usage_samples/"

    Response body for curl GET example

    {
        "data": [
            {
                "bytes_in": 3648,
                "bytes_out": 15911,
                "created_at": "2021-02-08T22:21:58.998417+00:00",
                "created_at_timeuuid": "0f3adfa8-6a5c-11eb-8f56-7e6ef7af9ffc",
                "period": 3660.3108481550007,
                "router": "https://www.cradlepointecm.com/api/v2/routers/2162719/",
                "uptime": 106087.10812882498
            },
            {
                "bytes_in": 3807,
                "bytes_out": 16438,
                "created_at": "2021-02-08T21:20:58.591900+00:00",
                "created_at_timeuuid": "89752a1a-6a53-11eb-87ed-368a313553a3",
                "period": 3660.362778883995,
                "router": "https://www.cradlepointecm.com/api/v2/routers/2162719/",
                "uptime": 102426.79728066998
            },
            {
                "bytes_in": 3969,
                "bytes_out": 18152,
                "created_at": "2021-02-08T20:19:58.058442+00:00",
                "created_at_timeuuid": "039c15e6-6a4b-11eb-85bc-32c6a22e5b89",
                "period": 3660.510760029996,
                "router": "https://www.cradlepointecm.com/api/v2/routers/2162719/",
                "uptime": 98766.434501786
            }
            ... 
            ],
            "meta": {
                "limit": 20,
                "next": "https://www.cradlepointecm.com/api/v2/router_stream_usage_samples/?created_at_timeuuid__lt=21b87914-69ba-11eb-a826-267fb8b4f5d2"
            }
        }
     

    Example curl GET request/response to the router_stream_usage_samples endpoint with the created_at_timeuuid filter applied. This retrieves router_stream_usage_samples record with the created_at_timeuuid of 039c15e6-6a4b-11eb-85bc-32c6a22e5b89.

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/router_stream_usage_samples/?created_at_timeuuid=039c15e6-6a4b-11eb-85bc-32c6a22e5b89"

    Response body for curl GET example

    {
                "data": [
                    {
                        "bytes_in": 3969,
                        "bytes_out": 18152,
                        "created_at": "2021-02-08T20:19:58.058442+00:00",
                        "created_at_timeuuid": "039c15e6-6a4b-11eb-85bc-32c6a22e5b89",
                        "period": 3660.510760029996,
                        "router": "https://www.cradlepointecm.com/api/v2/routers/2162719/",
                        "uptime": 98766.434501786
                    }
                ],
                "meta": {
                    "limit": 20,
                    "next": null
                }
            }

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.

Supported methods: GET, PUT, DELETE.
  • routers Endpoint Fields and Filters
  • This table lists the fields associated with the routers endpoint. Fields with operators specified in the Filter column indicate that those fields can be used as filters.

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

    Endpoint base path:

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

    IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
    Correct format:    https://www.cradlepointecm.com/api/v2/<endpoint name>/
    Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
  • Tips for Using the NetCloud API
  • When making API calls with curl in a console session, it can be helpful to define variables for your API keys, payloads, and the base URL of the endpoint for re-use with each curl statement.
    Please note that the method for setting variables in your console of choice can vary depending on the console/OS used. These variable definition examples are BASH specific; other console tools can require slightly different syntax to define these variables in a console session.

    • X_ECM_API_ID="<X-ECM-API-ID>"
    • X_ECM_API_KEY="<X-ECM-API-KEY>"
    • X_CP_API_ID="<X-CP-API-ID>"
    • X_CP_API_KEY="<X-CP-API-KEY>"
    • -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY"
    • URL="https://www.cradlepointecm.com/api/v2/routers/"
    • BODY = -d '{"<field name>": "<field value>"}

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

  • GET Examples
  • Example curl GET request/response to the routers endpoint without filters applied.

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/routers/"

    Response body for curl GET example

    {"data": [{"account": "https://www.cradlepointecm.com/api/v2/accounts/<account number>/", "actual_firmware": "https://www.cradlepointecm.com/api/v2/firmwares/877/", "asset_id": null, "config_status": "synched", "configuration_manager": "https://www.cradlepointecm.com/api/v2/routers/861605/configuration_manager/", "created_at": "2018-04-24T21:53:32.315171+00:00", "custom1": null, "custom2": null, "description": "My AP Twenty Two", "device_type": "access_point", "full_product_name": "AP22", "group": "https://www.cradlepointecm.com/api/v2/groups/85136/", "id": "861605", "ipv4_address": "65.153.116.34", "last_known_location": null, "locality": "US/Mountain", "mac": "00:30:44:24:61:54", "name": "AP22-154", "product": "https://www.cradlepointecm.com/api/v2/products/48/", "reboot_required": false, "resource_url": "https://www.cradlepointecm.com/api/v2/routers/861605/", "serial_number": "WA1801AA001172", "state": "online", "state_updated_at": "2021-02-04T17:29:05.075116+00:00", "target_firmware": "https://www.cradlepointecm.com/api/v2/firmwares/877/", "updated_at": "2021-01-19T22:04:42.650617+00:00", "upgrade_pending": false}, {"account": "https://www.cradlepointecm.com/api/v2/accounts/<account number>/", "actual_firmware": null, "asset_id": null, "config_status": "synched", "configuration_manager": "https://www.cradlepointecm.com/api/v2/routers/1437919/configuration_manager/", "created_at": "2019-07-31T03:11:52.746361+00:00", "custom1": null, "custom2": null, "description": null, "device_type": "access_point", "full_product_name": "unknown", "group": null, "id": "1437919", "ipv4_address": null, "last_known_location": null, "locality": "US/Mountain", "mac": "00:30:44:24:61:54", "name": "AP22-154", "product": "https://www.cradlepointecm.com/api/v2/products/48/", "reboot_required": false, "resource_url": "https://www.cradlepointecm.com/api/v2/routers/1437919/", "serial_number": null, "state": "initialized", "state_updated_at": null, "target_firmware": null, "updated_at": "2020-11-11T23:08:00.746990+00:00", "upgrade_pending": false}, {"account": "https://www.cradlepointecm.com/api/v2/accounts/<account number>/", "actual_firmware": "https://www.cradlepointecm.com/api/v2/firmwares/2958/", "asset_id": null, "config_status": "synched", "configuration_manager": "https://www.cradlepointecm.com/api/v2/routers/2162719/configuration_manager/", "created_at": "2020-11-05T23:13:37.346456+00:00", "custom1": null, "custom2": null, "description": null, "device_type": "router", "full_product_name": "AER2200-600M", "group": "https://www.cradlepointecm.com/api/v2/groups/216763/", "id": "2162719", "ipv4_address": "160.2.177.156", "last_known_location": "https://www.cradlepointecm.com/api/v2/locations/731218/", "locality": "US/Mountain", "mac": "00:30:44:47:CB:09", "name": "AER2200-b09", "product": "https://www.cradlepointecm.com/api/v2/products/41/", "reboot_required": false, "resource_url": "https://www.cradlepointecm.com/api/v2/routers/2162719/", "serial_number": "MM202300000212", "state": "online", "state_updated_at": "2021-02-08T02:17:58.389788+00:00", "target_firmware": "https://www.cradlepointecm.com/api/v2/firmwares/2958/", "updated_at": "2021-02-08T01:52:25.628645+00:00", "upgrade_pending": false}], "meta": {"limit": 20, "next": null, "offset": 0, "previous": null}}
     

    Example curl GET request/response to the routers endpoint with the ID filter applied. This retrieves the routers object with the ID "861605."

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/routers/?id=861605"

    Response body for curl GET example

    {"data": [{"account": "https://www.cradlepointecm.com/api/v2/accounts/<account number>/", "actual_firmware": "https://www.cradlepointecm.com/api/v2/firmwares/877/", "asset_id": null, "config_status": "synched", "configuration_manager": "https://www.cradlepointecm.com/api/v2/routers/861605/configuration_manager/", "created_at": "2018-04-24T21:53:32.315171+00:00", "custom1": null, "custom2": null, "description": "My AP Twenty Two", "device_type": "access_point", "full_product_name": "AP22", "group": "https://www.cradlepointecm.com/api/v2/groups/85136/", "id": "861605", "ipv4_address": "65.153.116.34", "last_known_location": null, "locality": "US/Mountain", "mac": "00:30:44:24:61:54", "name": "AP22-154", "product": "https://www.cradlepointecm.com/api/v2/products/48/", "reboot_required": false, "resource_url": "https://www.cradlepointecm.com/api/v2/routers/861605/", "serial_number": "WA1801AA001172", "state": "online", "state_updated_at": "2021-02-04T17:29:05.075116+00:00", "target_firmware": "https://www.cradlepointecm.com/api/v2/firmwares/877/", "updated_at": "2021-01-19T22:04:42.650617+00:00", "upgrade_pending": false}], "meta": {"limit": 20, "next": null, "offset": 0, "previous": null}}
  • PUT Examples
  • Example curl PUT request/response to the routers endpoint. This updates the name of the group matching the ID "861605".

    curl -v -X PUT -H "X-ECM-API-ID:40961453-652c-48bc-8445-2cfeb36d2c4a" -H "X-ECM-API-KEY:d02aacae1b4b77967014b7270812e8a465ac3174" -H "X-CP-API-ID:a939a410" -H "X-CP-API-KEY:808163e5193491974cd55eda5120ed9d" -H "Content-Type:application/json" "https://www.cradlepointecm.com/api/v2/routers/861605/" -d '{
            "name": "My AP-22"
            }'

    Response body for curl PUT example

    {"account": "https://www.cradlepointecm.com/api/v2/accounts/<account number>/", "actual_firmware": "https://www.cradlepointecm.com/api/v2/firmwares/877/", "asset_id": null, "config_status": "synched", "configuration_manager": "https://www.cradlepointecm.com/api/v2/routers/861605/configuration_manager/", "created_at": "2018-04-24T21:53:32.315171+00:00", "custom1": null, "custom2": null, "description": "My AP Twenty Two", "device_type": "access_point", "full_product_name": "AP22", "group": "https://www.cradlepointecm.com/api/v2/groups/85136/", "id": "861605", "ipv4_address": "65.153.116.34", "last_known_location": null, "locality": "US/Mountain", "mac": "00:30:44:24:61:54", "name": "My AP-22", "product": "https://www.cradlepointecm.com/api/v2/products/48/", "reboot_required": false, "resource_url": "https://www.cradlepointecm.com/api/v2/routers/861605/", "serial_number": "WA1801AA001172", "state": "online", "state_updated_at": "2021-02-04T17:29:05.075116+00:00", "target_firmware": "https://www.cradlepointecm.com/api/v2/firmwares/877/", "updated_at": "2021-02-08T20:20:33.338472+00:00", "upgrade_pending": false}
  • DELETE Example
  • Example curl DELETE request/response to the routers endpoint. This deletes the device matching the ID passed in the route.

    curl -v -X DELETE -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/routers/861605/"

    Successful DELETE actions return a 204 response with no content in the body.

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 status of a speed-test job and view the results of completed speed tests. The speed_test endpoint displays speed-test results in the same format as speed test results in NetCloud Manager (NCM).

Supported methods: GET, POST, DELETE.
  • speed_test Endpoint Fields and Filters
  • This table lists the fields associated with the speed_test endpoint. Fields with operators specified in the Filter column indicate that those fields can be used as filters.

    Parameter Data Type Filter Sort Expand Description
    account url =, __in Account that owns the object
    config json config object
    id int Job object ID

    The config object

    Parameter Data Type Description
    host url URL of Speedtest Server
    max_test_concurrency int Number of maximum simultaneous tests to server (1-50)
    net_device_ids int[] List of net_device IDs (up to 10,000 net_device IDs per request)
    port int TCP port for test
    size int Number of bytes to transfer
    test_timeout int Test Timeout
    test_type string TCP Download, TCP Upload, TCP Latency
    time int Test Time
    Note: * indicates the attribute is required for PUT and POST requests.

    Endpoint base path:

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

    IMPORTANT: URLs for endpoints MUST have a trailing forward slash. If a trailing slash is not present the call to the endpoint is automatically redirected, resulting in two calls attributed to your account.
    Correct format:    https://www.cradlepointecm.com/api/v2/<endpoint name>/
    Incorrect format: https://www.cradlepointecm.com/api/v2/<endpoint name>
  • Tips for Using the NetCloud API
  • When making API calls with curl in a console session, it can be helpful to define variables for your API keys, payloads, and the base URL of the endpoint for re-use with each curl statement.
    Please note that the method for setting variables in your console of choice can vary depending on the console/OS used. These variable definition examples are BASH specific; other console tools can require slightly different syntax to define these variables in a console session.

    • X_ECM_API_ID="<X-ECM-API-ID>"
    • X_ECM_API_KEY="<X-ECM-API-KEY>"
    • X_CP_API_ID="<X-CP-API-ID>"
    • X_CP_API_KEY="<X-CP-API-KEY>"
    • -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY"
    • URL="https://www.cradlepointecm.com/api/v2/speed_test/"
    • BODY = -d '{"<field name>": "<field value>"}

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

  • GET Examples
  • Example curl GET request/response to the speed_test endpoint using a speed test ID as a filter.

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/speed_test/47535/"

    Response body for curl GET example

    {
        "account": "https://www.cradlepointecm.com/api/v2/accounts/1/",
        "config": {
        "host": "YOURTESTSERVER.COM",
        "max_test_concurrency": 5,
        "net_device_ids": [
          12345678
        ],
        "port": 12865,
        "size": null,
        "test_timeout": 10,
        "test_type": "TCP Download",
        "time": 10
        },
        "created_at": "2019-02-06T15:16:16.240612+00:00",
        "id": "47535",
        "progress": {
        "completed": 1,
        "total_count": 1
        },
        "resource_uri": "https://www.cradlepointecm.com/api/v2/speed_test/47535/",
        "results": [
          {
        "created_at": "2019-02-06 15:16:16.260749+00:00",
        "net_device_id": 12345678,
        "results": "TCP Download Test Timestamp: 2019-02-18 16:14:56 Duration: 10.01 Seconds Client Received: 69.6 MB Client Sent: 0 bytesServer Received: 0 bytes Server Sent: 70.4 MB Download Throughput: 58.34 Mbps",
        "router_id": 123456,
        "state": "success",
        "updated_at": "2019-02-06 15:16:19.573507+00:00"
        }
        ],
        "state": "complete",
        "updated_at": "2019-02-06T15:17:16.362784+00:00"
        }  
     
  • POST Examples
  • Example curl POST request/response to the speed_test endpoint.

    curl -v -X POST -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" -H "Content-Type:application/json" "https://www.cradlepointecm.com/api/v2/speed_test/" -d '{
            "account": "https://www.cradlepointecm.com/api/v2/accounts/1/",
              "config": {
              "host": "YOURTESTSERVER.COM",
              "max_test_concurrency": 5,
              "net_device_ids": [
                  12345678
              ],
              "port": 12865,
              "size": null,
              "test_timeout": 10,
              "test_type": "TCP Download",
              "time": 10
          }
        }
        

    Response body for curl POST example

    {
        "account": "https://www.cradlepointecm.com/api/v2/accounts/1/",
        "config": {
            "host": "YOURTESTSERVER.COM",
            "max_test_concurrency": 5,
            "net_device_ids": [
                12345678
            ],
            "port": 12865,
            "size": null,
            "test_timeout": 10,
            "test_type": "TCP Download",
            "time": 10
        },
        "created_at": "2019-02-06T15:16:16.240612+00:00",
        "id": "47535",
        "progress": null,
        "resource_uri": "https://www.cradlepointecm.com/api/v2/speed_test/47535/",
        "results": null,
        "state": "created",
        "updated_at": "2019-02-06T15:16:16.240636+00:00"
    }
        
  • DELETE Example
  • Example curl DELETE request/response to the speed_test endpoint. This deletes the group matching the ID passed in the route.

    curl -v -X DELETE -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/speed_test/{id}/"

    Successful DELETE actions return a 204 response with no content in the body.

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. POST requests to this endpoint return a 201 Created response to indicate an alert push destination record was created successfully and can be used in the HTTP_destinations field of an alert rule configuration.

Supported methods:POST.
  • test_alert_push_destinations Endpoint Fields and Filters
  • This table lists the fields associated with the test_alert_push_destinations endpoint. Fields with operators specified in the Filter column indicate that those fields can be used as filters.

    Parameter Data Type Filter Sort Expand Description
    destination_config_id* timeuuid Unique ID for destination for which a test push will be initiated.
    Note: * indicates the attribute is required for POST requests.

    Endpoint base path:

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

    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>
  • Tips for Using the NetCloud API
  • When making API calls with curl in a console session, it can be helpful to define variables for your API keys, payloads, and the base URL of the endpoint for re-use with each curl statement.
    Please note that the method for setting variables in your console of choice can vary depending on the console/OS used. These variable definition examples are BASH specific; other console tools can require slightly different syntax to define these variables in a console session.

    • X_ECM_API_ID="<X-ECM-API-ID>"
    • X_ECM_API_KEY="<X-ECM-API-KEY>"
    • X_CP_API_ID="<X-CP-API-ID>"
    • X_CP_API_KEY="<X-CP-API-KEY>"
    • -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY"
    • URL="https://www.cradlepointecm.com/api/v2/test_alert_push_destinations/"
    • BODY = -d '{"<field name>": "<field value>"}

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

  • POST Examples
  • Example curl POST request/response to the test_alert_push_destinations endpoint to test an Alert Push Destination.

    curl -v -X POST -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" -H "Content-Type:application/json" "https://www.cradlepointecm.com/api/v2/test_alert_push_destinations/" -d '{
          "destination_config_id": “9b98af58-6703-11eb-8aef-42edcb7bf284”
          }
        

    Responses to successful POSTs to the test_alert_push_destinations endpoint return a 201 status code (created) and an empty response body.

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.

Supported methods: GET.
  • users Endpoint Fields and Filters
  • This table lists the fields associated with the users endpoint. Fields with operators specified in the Filter column indicate that those fields can be used as filters.

    Parameter Data Type Filter Sort Expand Description Permissions
    account url {=, __in, __gt, __lt} URL for the account Read Only
    email string {=, __in} A user's email address Read Only
    first_name string First name of user Read Only
    id int {=, __in} User ID Read Only
    last_name string User last name Read Only
    username string {=, __in} Username of user Read Only

    Endpoint base path:

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

    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>
  • Tips for Using the NetCloud API
  • When making API calls with curl in a console session, it can be helpful to define variables for your API keys, payloads, and the base URL of the endpoint for re-use with each curl statement.
    Please note that the method for setting variables in your console of choice can vary depending on the console/OS used. These variable definition examples are BASH specific; other console tools can require slightly different syntax to define these variables in a console session.

    • X_ECM_API_ID="<X-ECM-API-ID>"
    • X_ECM_API_KEY="<X-ECM-API-KEY>"
    • X_CP_API_ID="<X-CP-API-ID>"
    • X_CP_API_KEY="<X-CP-API-KEY>"
    • -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY"
    • URL="https://www.cradlepointecm.com/api/v2/users/"
    • BODY = -d '{"<field name>": "<field value>"}

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

  • GET Examples
  • Example curl GET request/response to the users endpoint without filters applied.

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/users/"

    Response body for curl GET example

    {
        "data": [
            {
                "account": "https://www.cradlepointecm.com/api/v2/accounts/<account number>/",
                "email": "jsmithn@some.com",
                "first_name": "John",
                "id": "63944",
                "last_name": "Smith",
                "resource_url": "https://www.cradlepointecm.com/api/v2/users/<id>/",
                "username": "038Bd0s1O9tzah0g"
            },
            {
                "account": "https://www.cradlepointecm.com/api/v2/accounts/<account number>/",
                "email": "albert@some.com",
                "first_name": "Albert",
                "id": "111032",
                "last_name": "Wilson",
                "resource_url": "https://www.cradlepointecm.com/api/v2/users/<id>/",
                "username": "muU8o4fXj1IKwzuq"
            }
        ],
        "meta": {
            "limit": 20,
            "next": null,
            "offset": 0,
            "previous": null
        }
    }
     

    Example curl GET request/response to the users endpoint with the ID filter applied.

    curl -v -X GET -H "X-ECM-API-ID:$X_ECM_API_ID" -H "X-ECM-API-KEY:$X_ECM_API_KEY" -H "X-CP-API-ID:$X_CP_API_ID" -H "X-CP-API-KEY:$X_CP_API_KEY" "https://www.cradlepointecm.com/api/v2/users/?id=111032"

    Response body for curl GET example

    {
        "data": [
            {
                "account": "https://www.cradlepointecm.com/api/v2/accounts/<account number>/",
                "email": "albert@some.com",
                "first_name": "Albert",
                "id": "111032",
                "last_name": "Wilson",
                "resource_url": "https://www.cradlepointecm.com/api/v2/users/111032/",
                "username": "muU8o4fXj1IKwzuq"
            }
        ],
        "meta": {
            "limit": 20,
            "next": null,
            "offset": 0,
            "previous": null
        }
    }
            

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


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 API key. This can affect production devices and data!

    Sample Code

    The following code samples demonstrate how to use the NetCloud Push API webhook and provide general examples of how to query the NCM REST API.

    NetCloud Alerts Push API Webhook

    Webhooks provide a simplified messaging standard (RFC8030) for communication between remote applications. Application inter-messaging is often accomplished using a message queueing/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 route 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.

    Some examples of webhooks used in production are by Gitlab and AWS:

    • Cloudwatch receives a Gitlab message that a code repository has been updated. Cloudwatch's webhook downloads the updated files and makes them available on its content delivery network.
    • Slack receives a Gitlab message after branch is merged to master in Gitlab. Slack's webhook posts a summary of the message to a specified channel.
    • Jira receives a Gitlab message when a branch is merged. Jira's webhook uses the message to update the status of a ticket.

    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 allow the message to be validated by your webhook.
    3. Test the Alert Push Destination by using the test_alert_push_destination endpoint.
    4. 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.

     

    Push Alert Overview

     

    Example Push Body Response Payload

    Note: The content in the "info" field varies with the type of alert. The type of alert is identified from the outer "type" field (last field in example below).

      { 
        "account": 3,
        "created_at": "2021-02-05 21:12:50.639320+00:00",
        "created_at_timeuuid": "e760426e-67f6-11eb-aa22-ce836cfbb4cd",
        "detected_at": "2021-02-05 21:12:49.712499+00:00",
        "friendly_info": "User admin has logged into the router from 192.168.0.33.",
        "info": {
            "time": [
                "2021-02-05 21:12:49",
                "UTC"
            ],
            "ip": "192.168.0.33",
            "user": "admin",
            "type": "login_success"
        },
        "router": 1234567,
        "type": "login_success"
    }
    
      

    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' );
    }    
      

    Sample Code in Python

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

    import json
    import requests
    
    url = 'https://www.cradlepointecm.com/api/v2/routers/'
    
    headers = {
        'X-CP-API-ID': '…',
        'X-CP-API-KEY': '…',
        'X-ECM-API-ID': '…',
        'X-ECM-API-KEY': '…',
        'Content-Type': 'application/json' 
    }
    
    # Get routers
    while url:
        req = requests.get(url, headers=headers)
        routers_resp = req.json()
                   
        # Get URL for next set of resources
        url = routers_resp['meta']['next']
    

    Net device usage and signal samples

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

    import json
    import requests
    
    
    API_OBJ_REQUEST_SIZE = 100
    API_OBJ_RESPONSE_SIZE = 500
    
    START_DATE = '2017-10-19'
    END_DATE = '2017-10-20'
    
    
    # Chunk lists into blocks
    def chunker(seq, size):
        return (seq[pos:pos + size] for pos in range(0, len(seq), size))
    
    
    # Get the next url, at completion return None
    def next_url(resp):
        if resp['meta']['next']:
            url = resp['meta']['next']
        else:
            url = None
    
        return url
    
    
    # Fill in your API keys here
    headers = {
        'X-CP-API-ID': '...',
        'X-CP-API-KEY': '...',
        'X-ECM-API-ID': '...',
        'X-ECM-API-KEY': '...',
        'Content-Type': 'application/json'
    }
    
    
    # Get net_devices
    net_device_ids = set()
    url = 'https://www.cradlepointecm.com/api/v2/net_devices/?limit={}'. \
        format(API_OBJ_RESPONSE_SIZE)
    while url:
        req = requests.get(url, headers=headers)
        resp = req.json()
        for net_device in resp['data']:
            net_device_ids.add(int(net_device['id']))
        url = next_url(resp)
    
    
    # Get usage samples
    print('bytes_in,bytes_out,created_at,created_at_timeuuid,'
          'net_device,period,uptime')
    for net_devices in chunker(sorted(net_device_ids), API_OBJ_REQUEST_SIZE):
        url = 'https://www.cradlepointecm.com/api/v2/net_device_usage_samples/' \
            '?limit={}'.format(API_OBJ_RESPONSE_SIZE)
        url += '&net_device__in={}'.format(','.join(map(str, net_devices)))
        url += '&created_at__gt={}&created_at__lt={}'.format(START_DATE, END_DATE)
        url += '&order_by=created_at_timeuuid'
    
        while url:
            req = requests.get(url, headers=headers)
            resp = req.json()
            if (len(resp['data']) > 0):
                for net_device in resp['data']:
                    print('{},{},{},{},{},{},{}'.format(
                        net_device['bytes_in'],
                        net_device['bytes_out'],
                        net_device['created_at'],
                        net_device['created_at_timeuuid'],
                        net_device['net_device'],
                        net_device['period'],
                        net_device['uptime']))
            url = next_url(resp)
    
    
    # Get signal samples
    print('created_at,created_at_timeuuid,ecio,net_device,rssi,'
          'signal_percent,sinr,uptime')
    for net_devices in chunker(sorted(net_device_ids), API_OBJ_REQUEST_SIZE):
        url = 'https://www.cradlepointecm.com/api/v2/net_device_signal_samples/' \
            '?limit={}'.format(API_OBJ_RESPONSE_SIZE)
        url += '&net_device__in={}'.format(','.join(map(str, net_devices)))
        url += '&created_at__gt={}&created_at__lt={}'.format(START_DATE, END_DATE)
        url += '&order_by=created_at_timeuuid'
    
        while url:
            req = requests.get(url, headers=headers)
            resp = req.json()
            if (len(resp['data']) > 0):
                for net_device in resp['data']:
                    print('{},{},{},{},{},{},{},{}'.format(
                        net_device['created_at'],
                        net_device['created_at_timeuuid'],
                        net_device['ecio'],
                        net_device['net_device'],
                        net_device['rssi'],
                        net_device['signal_percent'],
                        net_device['sinr'],
                        net_device['uptime']))
            url = next_url(resp)
    
        
    

    Sample Code in Shell Script

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

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

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

    Sample Code in JAVA

    import java.util.*;
    import java.io.BufferedReader;
    import java.io.DataOutputStream;
    import java.io.InputStreamReader;
    import java.net.HttpURLConnection;
    import java.net.URL;
    
    import javax.net.ssl.HttpsURLConnection;
    
    public class HttpURLConnectionExample {
    
    	public static void main(String[] args) throws Exception {
    		HttpURLConnectionExample http = new HttpURLConnectionExample();
    		http.sendGet();
    	}
    
    	// HTTP GET request
    	private void sendGet() throws Exception {
    		String url = "https://www.cradlepointecm.com/api/v2/accounts/";		
    		URL obj = new URL(url);
    		HttpURLConnection con = (HttpURLConnection) obj.openConnection();
    
    		// optional default is GET
    		con.setRequestMethod("GET");
    
    		//add request header
    		HttpURLConnectionExample http = new HttpURLConnectionExample();
    		http.set_headers(con);
    		int responseCode = con.getResponseCode();
    
    		System.out.println("\nSending 'GET' request to URL : " + url);
    		System.out.println("Response Code : " + responseCode);
    
                    Scanner s = new Scanner(con.getInputStream());
                    System.out.println("Response : " + s.useDelimiter("\0").next());	
    
    	}
    
            public HttpURLConnection set_headers(HttpURLConnection con)
    	{
                    con.setRequestProperty("x-ecm-api-id", "...");
                    con.setRequestProperty("x-ecm-api-key", "...");
                    con.setRequestProperty("x-cp-api-id", "...");
                    con.setRequestProperty("x-cp-api-key", "...");
                    con.setRequestProperty("Accept", "*/*");
                    return con;
    	}
    }
    

    Sample Code in PHP

    <?php
    $url = 'https://www.cradlepointecm.com/api/v2/routers/';
    $headers = array(
        'X-CP-API-ID: ...',
        'X-CP-API-KEY: ...',
        'X-ECM-API-ID: ...',
        'X-ECM-API-KEY: ...', 
        'Content-Type: application/json' 
    );
    
    $req = curl_init();
    curl_setopt_array($req, array(    
        CURLOPT_URL => $url,
     CURLOPT_HTTPHEADER => $headers, 
    ));
    
    $result = curl_exec($req);
    $res_info = curl_getinfo($req);
    echo $res_info['http_code'];
    curl_close($req);
    ?>
    

    Q&A

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    Filtering

    Filter Syntax:

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

    Generic Filters

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

    Examples:

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

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

    Sorting

    Partial Results:

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

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

    Examples:

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

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

    Expands

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

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

    Examples:

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

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

    Paging

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

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

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

    Examples:

    import requests
    
    headers = {
        'X-CP-API-ID': '…',
        'X-CP-API-KEY': '…',
        'X-ECM-API-ID': '…',
        'X-ECM-API-KEY': '…',
        'Content-Type': 'application/json',
        'Accept': '*/*'
    }
    
    result = []
    #Get next 50 devices
    url = 'https://www.cradlepointecm.com/api/v2/routers/?offset=50&limit=50'
    
        #loop to get all the data
        while url != None:
    
            req = requests.get(url, headers=headers)
            alert_data = req.json()
            result.append(alert_data)
            meta = alert_data['meta']
            url = meta['next']
          

    Glossary

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

    Configuration in API V2

    This document describes the conventions for using the configuration-related endpoints and how to extend those conventions.

    There are two endpoints for working with device configurations. One endpoint is for individual-device configs, the other is for group configs.

    Endpoints:

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

    Individual Device Configurations

    Individual device configs are managed by the configuration_managers endpoint

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

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

    Schema

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

    The account is a link to the same account that the device links to.

    The actual config shows the last diff received from the router. It is only valid for Series 3 routers (see differences between series 2 and series 3 routers). Routers send diffs when they connect to NetCloud Manager (NCM) and whenever the config changes while they are connected. This config is always formatted to match the router's current actual firmware.

    The pending config is empty except for unsynced devices, and then it shows the changes waiting to be synced to the device when it connects or resumes config sync. If the device's actual firmware and target firmware are different, the pending field appears empty even if there are pending changes. This is because the changes cannot be computed until the device syncs its firmware version. (Comparing configs for different firmware versions is not well-defined.)

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

    The resource_url is a self-referential link to the resource. It is not generally useful for anything.

    The version_number starts at zero and increments any time the target config changes. This is used as part of the sync protocol with the device client. The device stores a copy of the last version_number it synced to in its own config, as ecm.config_version. When the device sends a config diff to NCM, NCM checks if the device has the latest version_number. If and only if it does, then NCM considers the device to be in-sync and accepts any local changes. If it does not match, NCM ignores and even wipes local changes to force the device to sync. The API shows this number for informational purposes only. It automatically increments any time a change is made via the NCM UI, or the NetCloud API, or a local change is accepted, or if the config is migrated to a different firmware version.

    The router is a reference to the device.

    The id is the identifier for the resource. It sometimes matches the device id, but not necessarily, so do not assume they are the same.

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

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

    The configuration field shows the individual configuration for the device. The API can be used to change values in the config via PUT or PATCH, see the examples below. This config is formatted to match the device's target firmware (or actual, if there is no target). When the device's target firmware changes, NCM automatically migrates this config to be compatible with the new firmware.

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

    GET

    GET works as described in the API V2 documentation for all endpoints.

    Possible HTTP status codes:

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

    Supported filters:

    Field           Filters   Right-hand side
    =====           =======   ===============
    version_number  =,gt,lt   any non-negative integer
    router          =,in      device ID
    id              =,in      resource ID
    synched         =         true or false
    suspended       =         true or false
    

    Other supported URL parameters:

    offset  # first object to return (for paging)
    limit   # max objects to return (for paging)
    fields  # list of fields to return (for partial returns)
    expand  # convert a url field to an embedded object (only supported on some fields)
    

    See here for an explanation of the example format.

    GET Example: A Specific Manager

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

    The device is synced in the previous example. This is indicated by the following:

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

    You may have noticed that the target and actual fields do not look identical. In the lan section, the target has this:

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

    But the actual has this:

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

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

    PUT

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

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

    HTTP status codes:

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

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

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

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

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

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

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

    See here for a complete catalog of config validation errors.

    Other URL parameters:

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

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

    See here for an explanation of the example format.

    PUT Example: A Simple Config

    This enables GPS in the individual config:

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

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

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

    • the target field is updated
    • the version_number field is incremented
    • the synched field is set to false, and
    • the pending field shows the changes that will be (or already have been) sent to sync the device
    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 called "aleph"
    3. Assigns the aleph VLAN to a new LAN interface called "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. Thefollowing elments exist in the default config:

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

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

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

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

    The next removal looks very different: ["lan", "00000001-0d93-319d-8220-4a1fb0372b51"]. It is obviously trying to remove something from the default lan array, but is referring to the LAN it wants to remove not by its offset in the array, but by it's unique _id_ field value. "00000001-0d93-319d-8220-4a1fb0372b51" is the _id_ for the Guest LAN, as indicated by the default config, shown here in part:

    "lan": [
        {
            "name": "Primary LAN",
            "_id_": 00000000-0d93-319d-8220-4a1fb0372b51"
        },
        {
            "name": "Guest LAN",
            "_id_": 00000001-0d93-319d-8220-4a1fb0372b51"
        }
    ]
    

    If an array contains elements with an _id_ field then removals can refer to them by this instead of using the offset. Whenever a config is generated by the NCM UI, it uses the _id_ in its removals whenever possible.

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

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

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

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

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

    This may seem like senseless repitition but it is required.

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

    By now it is probably clear that hand-crafting a configuration is not easy. A better approach is to use the NCM UI to create a configuration to serve as a template and then to modify it as necessary for different devices. A typical workflow might be:

    1. Use the NCM 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 NCM to stop syncing a device via the API. Why would you stop the syncing of a device? You might not want devices to sync until you are done making and testing configuration changes on a test device. Or you might only want to sync devices at certain times.

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

    PATCH

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

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

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

    And this will do nothing at all:

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

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

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

    HTTP status codes:

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

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

    Also like PUT, it 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 here for an explanation of the example format.

    PATCH Example: Set Primary LAN IP Address

    Change the IP address of the Primary LAN to 192.168.30.1, leaving the other parts of the diff the same. Note the reply contains the entire diff; in this example it shows that PUT Example 1 to add a third LAN was already done, and the PATCH is an incremental change on top of that:

    > PATCH https://www.cradlepointecm.com/api/v2/configuration_managers/1234/
    > {
    >     "configuration": [
    >         {
    >             "lan": {
    >                 "00000000-0d93-319d-8220-4a1fb0372b51": {
    >                     "_id_": "00000000-0d93-319d-8220-4a1fb0372b51",
    >                     "ip_address": "192.168.30.1"
    >                 }
    >             }
    >         },
    >         []
    >     ]
    > }
    < 202 Accepted
    

    This example uses the Primary LAN's _id_ value as the key. 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/modify/write a "golden" config

    GET https://www.cradlepointecm.com/api/v2/groups/123/?fields=configuration
    # modify it for group 456
    PUT https://www.cradlepointecm.com/api/v2/groups/456/
    # modify it for group 789
    PUT https://www.cradlepointecm.com/api/v2/groups/789/
    ... etc ...
    

    Change the WiFi SSID and WPA2/PSK Passkey On Specific Routers

    PUT and PATCH require the URL of the configuration_managers ID endpoint and do not support filtering by router.id (or router.mac, router.name, etc):

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

    Add User

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

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

    Static IP for Ethernet WAN using WAN rule

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

    5.0 <= Firmware < 6.0

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

    Firmware >= 6.0

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

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

    Setting the APN for modem using LTE defaults WAN rule

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

    5.0 <= Firmware < 6.0

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

    Firmware >= 6.0

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

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

    Appendix

    Format of Examples

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

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

    > = client to server
    < = server to client
    

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

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

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

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

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

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

    _id_ Fields

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

    Some of these arrays are pre-populated with entries by default. For example, if you factory reset most devices (but not all!) you will find that they have two LAN entries and maybe five WAN rules.

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

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

    This refers to the LAN at index 1 which would be the second LAN. In most devices that would be the Guest LAN. But not necessarily, if the config has changed from the default. This might be a third LAN inserted before the Guest LAN. It might even be the Primary LAN, if the Guest LAN were somehow re-ordered to come first. This is an aliasing problem, where it is sometimes impossible to tell which element a config diff is referring to just by looking at it. The problem becomes worse when NCM begins to layer configs.

    The solution, introduced in firmware version 5.0, was to add a unique _id_ field to the elements of lists that have default values. The _id_ is a UUID. The lists that support them include the lan, wan.rules and various others, depending on the firmware version and product.

    The following example diff illustrates this by referring to the primary LAN by it's _id_: "00000000-0d93-319d-8220-4a1fb0372b51".

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

    For firmware versions 5.0 and greater this is the unambiguous way to refer to these array elements.

    For firmware versions prior to 5.0, these UUID fields are not supported by any arrays, so you must use string numerals to reference their position in the array. The first position is always "0".

    The default elements of these lists (ie, those which populate the list after a factory reset) all have pre-assigned _id_ field values. When adding a new element to such a list, you must provide your own UUID value.

    Here's a list of arrays with elements that use the _id_ field from a recent firmware build (6.1.0) as of this writing:

     asavie.tunnels
     certmgmt.certs
     dns.dnsmasq_options
     gre.tunnels
     identities.ip
     identities.mac
     identities.port
     lan
     openvpn.tunnels
     routing.access_list
     routing.bgp.access_list
     routing.bgp.community_list
     routing.prefix_list
     routing.route_map
     routing.tables
     security.app_sets
     security.ips.cat_cfg
     security.ips.sig_cfg
     security.zfw.filter_policies
     security.zfw.forwardings
     security.zfw.zones
     split_dns.domain_lists
     split_dns.servers
     system.gps.connections
     vpn.tunnels
     wan.rules
     wan.rules2
    

    Firmware Versioning And DTDs

    What constitutes a valid configuration? It depends on the firmware version and product. Every version of firmware has a Document Type Definition (DTD) that specifies the configuration-tree structure, the types of the elements, any limits on the range of values of elements, and whether an element must be specified or can be left blank. If a configuration does not conform to the DTD it is invalid.

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

    For example, currently all devices have a check that

    if `firewall.remote_admin.enabled` is `true` then either
        `firewall.remote_admin.secure_only` must be `true` or
        `firewall.remote_admin.port` must be provided.
    

    So even though this conforms to the DTD and would be accepted by NCM, the device would reject it:

    {
        "firewall": {
            "remote_admin": {
                "enabled": true,
                "secure_only": false
            }
        }
    }
    

    The DTD can change from one firmware version to another. This changes what constitutes a valid config. When a device's target firmware changes, NCM automatically attempts to migrate its configuration to make it compatible with the new version.

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

    Suspended Sync

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

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

    Once the problem is ascertained, the configuration should be changed to remove the error.

    Finally, to resume sync from the API, do a PUT with the suspended field set to False:

    PUT https://www.cradlepointecm.com/api/v2/configuration_managers/1234/
    {
        "suspended": false
    }
    

    Supported Products

    All currently available products are referred to as Series 3 products. Older series 2 products which are managed by NCM also have configuration_managers. However, their configuration format is different from series 3, and the fields and values are different. Nonetheless, one can still use this API to try and configure series 2 routers managed in NCM.

    Diffs

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

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

    For example, suppose a configuration looks like this:

    {
        "a": {
            "b": 1,
            "c": 2
        },
        "d": {
            "e": "hi",
            "f": "there"
        }
    }
    

    And the diff being applied looks like this:

    [
        {
            "a": {
                "d": 4,
                "c": 3
            }
        },
        [
            ["d", "e"]
        ]
    ]
    

    When applied, the diff will first remove element d.e, then, in no particular order, it will change element a.c and insert element a.d. Element a.b and d.f will be left as they are:

    {
        "a": {
            "d": 4,
            "c": 3,
            "b": 1
        },
        "d": {
            "f": "there"
        }
    }
    

    If a path in the removal list does not exist in the configuration, this is an error. If an element in the update dictionary is not described by the firmware's Document Type Definition (DTD), or if it is of the wrong type, that is also an error.

    An empty configuration diff looks like this:

    [{}, []]
    

    Group / Indie Layering

    Suppose the device is put into a group, and the group has a configuration like this:

    # Group config
    {
        "a": {
            "b": 1
            "c": 2
        }
    }
    

    If you GET the device's configuration, it will look exactly like that. Now suppose you PATCH the following to the device's configuration:

    # Patch to config
    {
        "a": {
            "b": 3,
            "d": 4
        }
    }
    

    NCM will save this as the device's individual configuration and update the target by layering it over the group. Now if you GET the device's configuration it will look like this:

    # Target config
    {
        "a": {
            "b": 3,
            "c": 2,
            "d": 4
        }
    }
    

    NCM changed a.b and inserted a.d. It left a.c alone, because the diff didn't mention it.

    What would happen if you then changed your mind and PUT with an empty config to the device’s configuration endpoint? NCM would clear the individual configuration, but the group configuration would stay the same, so the device's target configuration would go back to just being the group configuration:

    # Target config if indie cleared
    {
        "a": {
            "b": 1
            "c": 2
        }
    }
    

    What if instead you removed the device from the group? Then only the individual configuration would remain:

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

    NCM removed a.c from the target configuration, because a.c came from the group configuration.

    Passwords

    If you GET a config that has non-default passwords, the values are not shown. Instead, you see "*":

    > GET https://www.cradlepointecm.com/api/v2/configuration_managers/2/?fields=configuration
    < 200 Ok
    < {
    <    "configuration" : [
    <       {
    <          "wlan" : {
    <             "radio" : {
    <                "0" : {
    <                   "bss" : {
    <                      "0" : {
    <                         "wpapsk" : "*"
    <                      }
    <                   }
    <                }
    <             }
    <          }
    <       },
    <       []
    <    ]
    < }
    

    You can still set passwords through the API by sending them as cleartext:

    PATCH https://www.cradlepointecm.com/api/v2/configuration_managers/
    > {
    >    "configuration" : [
    >       {
    >          "wlan" : {
    >             "radio" : {
    >                "0" : {
    >                   "bss" : {
    >                      "0" : {
    >                         "radius0nasid" : null,
    >                         "wpapsk" : "2secret4Usorry"
    >                      }
    >                   }
    >                }
    >             }
    >          }
    >       },
    >       []
    >    ]
    > }
    < 202 Accepted
    

    They will be automatically encrypted.

    Validation Errors

    An "invalid path" error is reported anytime a diff refers to something that does not exist in the DTD. It does not matter if the reference is in the updates or the removals. For instance, both updates and removals are invalid here:

    [
        {
            "foo": "bar"
        },
        [
            ["baz", 6]
        ]
    ]
    

    Other errors are due to a wrong type or value:

    empty dict                                    # array can't be an empty dictionary
    not a dict                                    # struct must be dictionary
    invalid id                                    # _id_ not a UUID
    not a string
    url must have "http://" or "https://" prefix
    invalid url
    invalid ip address
    invalid ip address or dns name
    not a float type
    invalid mac address
    invalid ipv6 address
    too large
    negative invalid                              # ipv6_prefixlen must be >= 0
    not an integer
    invalid subnet mask
    invalid ipv4 address
    invalid ip address
    invalid option                                # select value must be from the list
    too large (max=n)
    number precision exceeded (max bits=n)        # u8, s8, u16, etc only allow 8 or 16 bits, etc
    too small(min=n)
    not a boolean
    bad array index
    not a list or dict                            # array must be a dict or list
    too short (min length=n)
    incorrect padding                             # encrypted password is corrupted
    too long (max length=n)
    invalid dns name
    

    Config Rollback

    Sometimes the device will validate a config and apply it, but then be unable to connect the WAN with the new settings. To protect against this situation, all firmware versions support a config rollback feature. After applying a config from NCM, if the device cannot contact NCM within 15 minutes it "undoes" the config change and reverts to the previous working version. When it reconnects to NCM after a rollback it informs NCM and config sync on the device is suspended.

    Differences From v1

    Sample v1 resource:

    "account" : "/api/v1/accounts/1/",
    "actual" : "/api/v1/configuration_managers/2/actual/",
    "configuration" : "/api/v1/configuration_managers/2/configuration/",
    "id" : "2",
    "lock" : "unlocked",
    "pending" : "/api/v1/configuration_managers/2/pending/",
    "pending_patch" : null,
    "resource_uri" : "/api/v1/configuration_managers/2/",
    "router" : "/api/v1/routers/2/",
    "suspended" : false,
    "synched" : true,
    "target" : "/api/v1/configuration_managers/2/target/",
    "version_number" : 83
    

    Sample v2 resource:

    "account" : "https://www.cradlepointecm.com/api/v2/accounts/1/",
    "actual" : [{}, []],
    "configuration" : [{}, []],
    "id" : "1108",
    "pending" : [{}, []],
    "resource_url" : "https://www.cradlepointecm.com/api/v2/configuration_managers/1108/",
    "router" : "https://www.cradlepointecm.com/api/v2/routers/1108/",
    "suspended" : false,
    "synched" : true,
    "target" : [{}, []],
    "version_number" : 0
    

    *Notable differences:

    • The fields which contain configuration diffs (configuration, actual, target and pending) are no longer URLs. They are contained right in the resource.
    • The pending_patch field has been removed. The same information is available in pending.
    • resource_uri has been renamed resource_url and is a full URL.
    • The account and router fields are full URLs.
    • The routers resource does not have a URL link to the corresponding configuration_managers. However, you can still find the corresponding configuration_manager by querying as in "Change the WiFi SSID and WPA2/PSK Passkey On Specific Routers" example

    Zscaler Configurations

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

    Zscaler example code

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

    Hardware Requirements

    • Cradlepoint AER 2100 or MBR1400v2
    • ZScaler service account

    Firmware Version

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