Mason Docs

Device API

Use Device APIs to retrieve information about the provisioned devices you have in the Mason Platform

If devices are de-provisioned, they will no longer be accessible via Mason Platform APIs

Device model

The following is a sample device model, represented in JSON

{
  "apps": [
    {
      "name": "company.division.application1",
      "version": "12345"
    },
    {
      "name": "company.division.application2",
      "version": "2454"
    }
  ],
  "battery": {
    "level": "81"
  },
  "connection": {
    "dataUsage": {
        "appsDataUsage": [
            {
                "packageNames": [
                    "com.myexample.app3"
                ],
                "uid": 10083,
                "usageCycles": [
                    {
                        "startTime": "2019-11-02T17:45:52Z",
                        "endTime": "2019-12-02T17:45:52Z",
                        "usages": [
                            {
                                "type": "wifi",
                                "bytesReceived": 484725,
                                "bytesSent": 46580
                            }
                        ]
                    },
                    {
                        "startTime": "2019-12-01T17:45:52Z",
                        "endTime": "2019-12-02T17:45:52Z",
                        "usages": [
                            {
                                "type": "wifi",
                                "bytesReceived": 0,
                                "bytesSent": 0
                            }
                        ]
                    }
                ]
            },
            {
                "packageNames": [
                    "org.example.app1"
                ],
                "uid": 10082,
                "usageCycles": [
                    {
                        "startTime": "2019-11-02T17:45:52Z",
                        "endTime": "2019-12-02T17:45:52Z",
                        "usages": [
                            {
                                "type": "wifi",
                                "bytesReceived": 5138957,
                                "bytesSent": 337008
                            }
                        ]
                    },
                    {
                        "startTime": "2019-12-01T17:45:52Z",
                        "endTime": "2019-12-02T17:45:52Z",
                        "usages": [
                            {
                                "type": "wifi",
                                "bytesReceived": 13357,
                                "bytesSent": 3925
                            }
                        ]
                    }
                ]
            },
            {
                "packageNames": [
                    "system"
                ],
                "uid": 1000,
                "usageCycles": [
                    {
                        "startTime": "2019-11-02T17:45:52Z",
                        "endTime": "2019-12-02T17:45:52Z",
                        "usages": [
                            {
                                "type": "wifi",
                                "bytesReceived": 81689926,
                                "bytesSent": 5423191
                            }
                        ]
                    },
                    {
                        "startTime": "2019-12-01T17:45:52Z",
                        "endTime": "2019-12-02T17:45:52Z",
                        "usages": [
                            {
                                "type": "wifi",
                                "bytesReceived": 245133,
                                "bytesSent": 64784
                            }
                        ]
                    }
                ]
            }
        ],
        "usageCycles": [
            {
                "startTime": "2019-10-26T08:16:55Z",
                "endTime": "2019-11-25T08:16:55Z",
                "usages": [
                    {
                        "type": "wifi",
                        "bytesReceived": 4278806,
                        "bytesSent": 4340376
                    }
                ]
            },
            {
                "startTime": "2019-11-24T08:16:55Z",
                "endTime": "2019-11-25T08:16:55Z",
                "usages": [
                    {
                        "type": "wifi",
                        "bytesReceived": 1029194,
                        "bytesSent": 1185728
                    }
                ]
            }
        ]
    },
    "bluetooth": {
        "enabled": false,
        "macAddress": "",
        "name": "",
        "pairedDevices": null
    },
    "sim": [
      {
        "carrier": "No service.",
        "countryiso": "us",
        "iccid": "6367377378783365457",
        "mcc": "420",
        "mnc": "525"
      },
      {
        "carrier": "No service.",
        "countryiso": "us",
        "iccid": "6367377378783365457",
        "mcc": "420",
        "mnc": "525"
      }
    ],
    "wifi": {
      "adapterMacAddress": "12:00:00:00:00:0",
      "bssid": "e0:ab:47:be:f6:c0",
      "enabled": true,
      "ipaddress": "172.20.8.174",
      "ssid": "\"BrandX_WiFi\""
    }
  },
  "createdAt": "1516239022",
  "family": "D450",
  "group": {
    "name": "Test Group",
    "self": "/v1/default/group/8989-3535-3233"
  },
  "id": "Praesentium expedita quo earum temporibus praesentium aut.",
  "imei": "359333090374045",
  "name": "TestDevice001",
  "os": {
    "configuration": {
      "device": "E81",
      "product": "default",
      "project": "myapplication",
      "version": "2"
    },
    "masonOS": {
      "incremental": "NX08351F",
      "release": "1.2.3"
    }
  },
  "status": {
    "op_updated": true,
    "apps_updated": true,
    "project_updated": true
  },
  "self": "/v1/default/device/40052b21-211c-4d1e-9e81-fec7e2f64582",
  "serialnumber": "40052b21-211c-4d1e-9e81-fec7e2f64582",
  "lastcheckin": "2019-06-26T15:47:42.269Z"
}

GET Device

https://api.bymason.com/v1/default/device/{id}

Retrieves the Device model for a single device.

Required API key scope(s)

  • fleet:read

For more information on scoping API keys, visit our guide for creating API keys

Sample request(s)

$ curl -H "Authorization: basic $API_KEY" api.bymason.com/v1/default/device/$DEVICE_ID

POST Device

https://api.bymason.com/v1/default/device/{id}

Updates Device attributes.

Required API key scope(s)

  • fleet:admin

For more information on scoping API keys, visit our guide for creating API keys

Request body

NameTypeDescription
namestringUpdates the Device attribute name

Sample request(s)

$ curl -H "Authorization: basic $API_KEY" -d '{"name":"TestDevice001"}' api.bymason.com/v1/default/device/$DEVICE_ID

GET Device Ping

https://api.bymason.com/v1/default/device/{id}/ping

Send a non-intrusive ping to the device. This will check if it is connected to the server without interacting with the device directly.

Required API key scope(s)

  • fleet:read

For more information on scoping API keys, visit our guide for creating API keys

Sample request(s)

$ curl -H "Authorization: basic $API_KEY" api.bymason.com/v1/default/device/$DEVICE_ID/ping

GET Devices

https://api.bymason.com/v1/default/device

Retrieves a list of Devices you have provisioned on the Mason Platform.

Required API key scope(s)

  • fleet:read

For more information on scoping API keys, visit our guide for creating API keys

Optional request parameters

ParameterDescriptionExample
limitLimit to number of devices returned/v1/default/device?limit=10
beforeRequest the previous page/v1/default/device?before=40052b21-211c-4d1e-9e81-fec7e2A64582
afterRequest the next page/v1/default/device?after=40052b21-211c-4d1e-9e81-fec7e2fA4582
nPerforms an exact match search query using the given term as the value to match/v1/default/device?n=Device001
qPerforms a partial match search query using the given term as the value to match/v1/default/device?q=A7SD32
typeSpecifies the field to lookup when performing an n or q search query. Valid options are all, imei, serial, or name. Defaults to all if omitted./v1/default/device?q=abc&type=all

Sample request(s)

$ curl -H "Authorization: basic $API_KEY" api.bymason.com/v1/default/device

Response body (JSON)

The response from the Devices endpoint is a collection of Device models. See the details of the Device model documented in our Device endpoint


POST Devices Ping

https://api.bymason.com/v1/default/device/ping

Send a non-intrusive ping to many devices at once. This will check if each device is connected to the server without interacting with any device directly.

Required API key scope(s)

  • fleet:read

For more information on scoping API keys, visit our guide for creating API keys

Request body

NameTypeDescription
devicesstring[]An array of strings, each that correspond to an id of a device provisioned to your Platform account

Sample request(s)

$ curl -H "Authorization: basic $API_KEY" -d '{"devices":["$DEVICE_ID_1","$DEVICE_ID_2", "$DEVICE_ID_3"]}' api.bymason.com/v1/default/device/ping

POST Devices Broadcast

https://api.bymason.com/v1/default/device/broadcast

Send an Android broadcast to an application on your device.

Want to learn more about Broadcasts on the Mason Platform? Visit our guide for creating Broadcasts on your Mason Device

Required API key scope(s)

  • fleet:read

For more information on scoping API keys, visit our guide for creating API keys

Request body

NameTypeDescription
devicesstring[]An array of strings, each that correspond to an id of a device provisioned to your Platform account
targetAppsstring[]An array of strings, each that correspond to the name of an application deployed to your device(s)
commandstringAny string
argsstring[]An array of strings, any string

Sample request(s)

$ curl
-H "Authorization: basic $API_KEY"
-d '{
"devices":[
"40052b21-211c-4d1e-9e81-fec7e2f64582",
"40052b21-211c-4d1e-9e81-fec7e2f64583"
],
"targetApps: ["com.example.myapplication"],
"command": "YOUR_COMMAND_HERE",
"args": ["arg1", "arg2"]
}'
api.bymason.com/v1/default/device/broadcast

POST Devices Refresh

https://api.bymason.com/v1/default/device/refresh

Send a Refresh message to a list of devices

Required API key scope(s)

  • fleet:admin

For more information on scoping API keys, visit our guide for creating API keys

Request body

NameTypeDescription
devicesstring[]An array of strings, each that correspond to an id of a device provisioned to your Platform account

Sample request(s)

$ curl
-H "Authorization: basic $API_KEY"
-d '{
"devices":[
"40052b21-211c-4d1e-9e81-fec7e2f64582",
"40052b21-211c-4d1e-9e81-fec7e2f64583"
],
}'
api.bymason.com/v1/default/device/refresh

POST Devices Update

https://api.bymason.com/v1/default/device/update

Send a message to a list of devices to check for updates.

Required API key scope(s)

  • fleet:admin

For more information on scoping API keys, visit our guide for creating API keys

Request body

NameTypeDescription
devicesstring[]An array of strings, each that correspond to an id of a device provisioned to your Platform account

Sample request(s)

$ curl
-H "Authorization: basic $API_KEY"
-d '{
"devices":[
"40052b21-211c-4d1e-9e81-fec7e2f64582",
"40052b21-211c-4d1e-9e81-fec7e2f64583"
],
}'
api.bymason.com/v1/default/device/update

POST Devices Reboot

https://api.bymason.com/v1/default/device/reboot

Send a reboot message a list of devices.

Rebooting your device will preserve the MasonOS configuration that was most recently deployed.

Required API key scope(s)

  • fleet:admin

For more information on scoping API keys, visit our guide for creating API keys

Request body

NameTypeDescription
devicesstring[]An array of strings, each that correspond to an id of a device provisioned to your Platform account

Sample request(s)

$ curl
-H "Authorization: basic $API_KEY"
-d '{
"devices":[
"40052b21-211c-4d1e-9e81-fec7e2f64582",
"40052b21-211c-4d1e-9e81-fec7e2f64583"
],
}'
api.bymason.com/v1/default/device/reboot

POST Devices Shutdown

https://api.bymason.com/v1/default/device/shutdown

Send a shutdown message a list of devices.

Your device will be inaccessible until it is manually rebooted. Proceed with caution.

Required API key scope(s)

  • fleet:admin

For more information on scoping API keys, visit our guide for creating API keys

Request body

NameTypeDescription
devicesstring[]An array of strings, each that correspond to an id of a device provisioned to your Platform account

Sample request(s)

$ curl
-H "Authorization: basic $API_KEY"
-d '{
"devices":[
"40052b21-211c-4d1e-9e81-fec7e2f64582",
"40052b21-211c-4d1e-9e81-fec7e2f64583"
],
}'
api.bymason.com/v1/default/device/shutdown

POST Devices Wipe

https://api.bymason.com/v1/default/device/wipe

Send a message to a list of devices to wipe themselves back to factory reset.

Visit our guide for performing a factory reset to learn more about this process

Required API key scope(s)

  • fleet:admin

For more information on scoping API keys, visit our guide for creating API keys

Request body

NameTypeDescription
devicesstring[]An array of strings, each that correspond to an id of a device provisioned to your Platform account

Sample request(s)

$ curl
-H "Authorization: basic $API_KEY"
-d '{
"devices":[
"40052b21-211c-4d1e-9e81-fec7e2f64582",
"40052b21-211c-4d1e-9e81-fec7e2f64583"
],
}'
api.bymason.com/v1/default/device/wipe