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)
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
| Name | Type | Description |
|---|---|---|
| name | string | Updates 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)
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
| Parameter | Description | Example |
|---|---|---|
| limit | Limit to number of devices returned | /v1/default/device?limit=10 |
| before | Request the previous page | /v1/default/device?before=40052b21-211c-4d1e-9e81-fec7e2A64582 |
| after | Request the next page | /v1/default/device?after=40052b21-211c-4d1e-9e81-fec7e2fA4582 |
| n | Performs an exact match search query using the given term as the value to match | /v1/default/device?n=Device001 |
| q | Performs a partial match search query using the given term as the value to match | /v1/default/device?q=A7SD32 |
| type | Specifies 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)
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
| Name | Type | Description |
|---|---|---|
| devices | string[] | 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"]}' api.bymason.com/v1/default/device/ping
Response body (JSON)
[
{
"deviceId": "DEVICE_ID_1",
"presence": {
"lastActive": {
"date": "2022-01-26T13:19:12Z"
},
"online": false
}
},
{
"deviceId": "DEVICE_ID_2",
"presence": {
"lastActive": {
"date": "2022-10-03T17:58:13Z"
},
"online": false
}
}
]
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
| Name | Type | Description |
|---|---|---|
| devices | string[] | An array of strings, each that correspond to an id of a device provisioned to your Platform account |
| targetApps | string[] | An array of strings, each that correspond to the name of an application deployed to your device(s) |
| command | string | Any string |
| args | string[] | 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
| Name | Type | Description |
|---|---|---|
| devices | string[] | 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
| Name | Type | Description |
|---|---|---|
| devices | string[] | 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
| Name | Type | Description |
|---|---|---|
| devices | string[] | 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
| Name | Type | Description |
|---|---|---|
| devices | string[] | 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
| Name | Type | Description |
|---|---|---|
| devices | string[] | An array of strings, each that correspond to an id of a device provisioned to your Platform account |