Skip to main content

Mason Platform APIs Docs (1.0)

Download OpenAPI specification:Download

The Mason Platform API is a series of REST routes that enable customers to perform operations against their fleet of devices and artifacts.

Endpoints

All endpoints are hosted on https://api.bymason.com/v1.

Authentication

All endpoints require authentication. Authentication is specified using API Keys. To use an API Key, set the Authorization header in your request to basic <api-key>. The full header should look as follows:

Authorization: basic <api-key>

To use an API Key against an endpoint, it needs to have the proper scope.

Scopes

Every user and API key has an associated list of scopes. A scope enables a level of access to APIs for the request send by the user or API key. Each endpoint will validate the incoming request has the required scope before processing the request. The scope hierarchy is shown below with a description of each scope.

  • account:owner: Full permissions for the account
    • fleet:admin: Grants administrator control over devices and groups
      • fleet:manager: Grants control over devices and groups
        • fleet:read: Grants read access on devices and groups
      • fleet:locate: Grants access to devices location data
      • notify:all: Grants send notifications for all notification types
        • notify:refresh: Grants send notifications to heartbeat
        • notify:check: Grants send notifications to check for updates
        • notify:reboot: Grants send notifications to reboot devices
        • notify:shutdown: Grants send notifications to shutdown devices
        • notify:wipe: Grants send notifications to wipe devices
        • notify:application: Grants send notifications to user-applications on devices
        • notify:refurbish: Grants send notifications to refurbish devices
    • xray:admin: Grants full use of Xray features
    • user:admin: Grants administrator control over users
      • user:read: Grants read access to users
    • registry:admin: Grants administrator control over the artifact registry
      • registry:read: Grants read access to the artifact registry
    • connect:admin: Grants administrator control over SIMs
      • connect:read: Grants read access to SIMs

Pagination

Many of the platform APIs contain paginated results. All pagination follow a standard token-based pattern. Results are always stored in the data value as a list. If there is a next page, the token is stored in the nextPage value. If there is a previous page, the token is stored in the prevPage value.

To request the next or previous page, send a subsequent request with the next or previous token as the after or before query parameter.

Below is a sample JSON response from the paginated devices endpoint:

https://api.bymason.com/device
{
  "data": [{...}],
  "prevPage": "cHJldmlvdXMgcGFnaW5hdGlvbiB0b2tlbgo=",
  "nextPage": "bmV4dCBwYWdpbmF0aW9uIHRva2VuCg=="
}

Given the above response, you can query the next page by setting the after query parameter with the nextPage token:

https://api.bymason.com/device?after=bmV4dCBwYWdpbmF0aW9uIHRva2VuCg==
{
  "data": [{...}],
  "prevPage": "cHJldmlvdXMgcGFnaW5hdGlvbiB0b2tlbgo=",
  "nextPage": "bmV4dCBwYWdpbmF0aW9uIHRva2VuCg=="
}

Status Codes

The Mason API will return one of the following status codes for each request.

Status Code Description
200 The request succeeded.
400 The request was malformed. Details will be in the error context.
401 The request had an invalid or missing API key.
403 The API key does not have the proper scope for the endpoint.
404 The requested resource does not exist.
500 Internal server error.

Errors

The Mason API uses a standard JSON body for all non-2XX status codes to represent errors. The body of the error response will follow the format:

{
  "type": "<error-type-category>",
  "context": "<error-message>"
}

An example error message for an Unauthorized error will look like:

{
  "type": "forbidden",
  "context": "The user does not have permission to take the desired action"
}

Timestamps

All timestamps used in the platform APIs are formatted using RFC3339, unless specified otherwise.

Devices

The Devices API endpoints enable you to monitor your fleet of devices.

List devices

Fetches a page of devices registered with your account.

Authorizations:
APIKeyAuth
query Parameters
limit
integer >= 1
Default: 100

Limits the number of items in a page of results

before
string

Request the previous page of results

after
string

Request the next page of results

orderByCol
string
Enum: "createdAt" "lastHeartbeat"

Column to sort the results

orderDir
string
Default: "asc"
Enum: "asc" "desc"

Direction to order the results (i.e., ascending or descending)

searchType
string
Enum: "partial" "exact"

Type of search to perform. If not provided, the search parameters will be ignored and all results returned.

searchQuery
string

Query to use for search

type
string
Enum: "all" "imei" "serial" "name"

Field to apply the search query to

deviceGroup
string

Filter results based on the Deployment Group name

appsUpdated
boolean
Enum: true false

Filter results based on whether the device's apps are updated

osUpdated
boolean
Enum: true false

Filter results based on whether the device's OS is updated

projectUpdated
boolean
Enum: true false

Filter results based on whether the device's project is updated

maxBatteryPercent
number

Filter results based on the max, last known, battery percentage of the device

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "nextPage": "eyJwIjoiZXlKelkyRnVTVzVrWlhoR2IzSjNZWEprSWpwdWRXeHNMQ0pzWVhOMFJYWmhiSFZoZEdWa1MyVjVJanB1ZFd4c0xDSnNhVzFwZENJNmJuVnNiSDBLIiwibCI6MTAwfQ==",
  • "prevPage": "eyJuIjoiZXlKUVlXZHBibUYwYVc5dUlqcDdJbXhwYldsMElqb3hMQ0p2Wm1aelpYUWlPakY5ZlFvPSIsImwiOjF9"
}

Read device

Fetches a device registered with your account by its unique id.

Authorizations:
APIKeyAuth
path Parameters
id
required
string <uuid>

Device ID

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Update device

Updates device attributes

Authorizations:
APIKeyAuth
path Parameters
id
required
string <uuid>

Device ID

Request Body schema: application/json
name
string

Device name

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "os": {
    },
  • "apps": [
    ],
  • "imei": "615022756680303",
  • "name": "Store 123 Device #2",
  • "self": "string",
  • "group": {
    },
  • "family": "D03",
  • "battery": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "connection": {
    },
  • "lastcheckin": "2019-08-24T14:15:22Z",
  • "serialnumber": "21BC01CF8DFF"
}

Device Actions

The Actions API endpoints enable you to send commands to your fleet of devices. Each action is queued to the device. The device processes it's queue of actions when it is online and has an internet connection. If the device is online when the action is sent, it will process the action immediately.

Send a Wipe Action

Sends a Wipe Action to a list of devices. A Wipe Action will perform a factory reset on the device. A factory reset will delete app-specific data and settings on the device, but will preserve the deployed project and configuration.

Authorizations:
APIKeyAuth
Request Body schema: application/json
devices
Array of strings <= 500 items

List of device ids to send an Action to

Responses

Request samples

Content type
application/json
{
  • "devices": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Send a Reboot Action

Sends a Reboot Action to a list of devices. A Reboot Action will power off and then power on the device.

Authorizations:
APIKeyAuth
Request Body schema: application/json
devices
Array of strings <= 500 items

List of device ids to send an Action to

Responses

Request samples

Content type
application/json
{
  • "devices": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Send an Update Check Action

Sends an Update Check Action to a list of devices. An Update Check Action tells the device to check in to the platform to get any updates. Updates are any artifacts deployed to the devices group, including Mason OS, project builds, and apps. If the device is out of date for any artifact, it will install the latest deployed version.

Authorizations:
APIKeyAuth
Request Body schema: application/json
devices
Array of strings <= 500 items

List of device ids to send an Action to

Responses

Request samples

Content type
application/json
{
  • "devices": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Send a Refresh Action

Sends a Refresh Action to a list of devices. A Refresh Action tells the device to report it's latest state to the platform. The state includes installed artifacts, networked devices, etc.

Authorizations:
APIKeyAuth
Request Body schema: application/json
devices
Array of strings <= 500 items

List of device ids to send an Action to

Responses

Request samples

Content type
application/json
{
  • "devices": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Send a Shutdown Action

Sends a Shutdown Action to a list of devices. A Shutdown Action will power off the device.

Authorizations:
APIKeyAuth
Request Body schema: application/json
devices
Array of strings <= 500 items

List of device ids to send an Action to

Responses

Request samples

Content type
application/json
{
  • "devices": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Send a Broadcast Action

Sends a Broadcast Action to a list of devices. A Broadcast is a mechanism to deliver a command to your Android application.

As a best practice, you should never send sensitive data over a broadcast. If you have sensitive data, it's best to send an identifier to your storage over the broadcast, or to encrypt the data.

Authorizations:
APIKeyAuth
Request Body schema: application/json
args
Array of strings

A list of arguments to send with the Command

command
string

Command to send to the applications

devices
Array of strings <= 500 items

List of device ids to send the Command to

targetApps
Array of arrays

List of applications to receive the Command on you devices

Responses

Request samples

Content type
application/json
{
  • "args": [
    ],
  • "command": "string",
  • "devices": [
    ],
  • "targetApps": [ ]
}

Response samples

Content type
application/json
{
  • "type": "string",
  • "context": "string"
}

Projects

The Project API endpoints enable you to view and manage your Mason projects. A Project is a collection of apps and configuration that can be deployed to a device.

List projects

Fetches a list of projects.

Authorizations:
APIKeyAuth
query Parameters
name
string

Project Name

before
string

Request the previous page of results

after
string

Request the next page of results

limit
integer >= 1
Default: 100

Limits the number of items in a page of results

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "nextPage": "eyJwIjoiZXlKelkyRnVTVzVrWlhoR2IzSjNZWEprSWpwdWRXeHNMQ0pzWVhOMFJYWmhiSFZoZEdWa1MyVjVJanB1ZFd4c0xDSnNhVzFwZENJNmJuVnNiSDBLIiwibCI6MTAwfQ==",
  • "prevPage": "eyJuIjoiZXlKUVlXZHBibUYwYVc5dUlqcDdJbXhwYldsMElqb3hMQ0p2Wm1aelpYUWlPakY5ZlFvPSIsImwiOjF9"
}

Create project

Creates a project.

Authorizations:
APIKeyAuth
Request Body schema: application/json
name
string [ 1 .. 500 ] characters ^[a-zA-Z0-9_\-]+$

Unique name of project

apiLevel
integer (APILevel)
Enum: 23 25 27 30
description
string [ 1 .. 10000 ] characters

Description of project

deviceFamily
string (DeviceFamily)
Enum: "D03" "F07" "D450" "D450A" "D450A1" "D450B" "C210" "F210" "F450" "G430" "G450" "I3399A" "A4100" "D215"

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "apiLevel": 23,
  • "description": "string",
  • "deviceFamily": "D03"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "apiLevel": 23,
  • "createdAt": "string",
  • "updatedAt": "string",
  • "description": "string",
  • "deviceFamily": "D03"
}

Read project

Fetches project details.

Authorizations:
APIKeyAuth
path Parameters
id
required
string <uuid>

Project ID

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "apiLevel": 23,
  • "createdAt": "string",
  • "updatedAt": "string",
  • "description": "string",
  • "deviceFamily": "D03"
}

Update project

Updates project details.

Authorizations:
APIKeyAuth
path Parameters
id
required
string <uuid>

Project ID

Request Body schema: application/json
description
string [ 1 .. 10000 ] characters

Description of project

Responses

Request samples

Content type
application/json
{
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "apiLevel": 23,
  • "createdAt": "string",
  • "updatedAt": "string",
  • "description": "string",
  • "deviceFamily": "D03"
}

Device

A Device is any Android based phone or tablet running Mason OS.

id
string <uuid>

Unique identifier for the device

object

Version codes describing which Mason OS is running

Array of objects (DeviceApps)

Apps deployed to the device via a Deployment Group

imei
string

International mobile equipment identity

name
string

Device name

self
string

Reference to this device

object

Device group the device currently belongs to

family
string (DeviceFamily)
Enum: "D03" "F07" "D450" "D450A" "D450A1" "D450B" "C210" "F210" "F450" "G430" "G450" "I3399A" "A4100" "D215"
object

Battery properties

createdAt
string <date-time>

Date device was added to the Mason account

object (Connection)

Information on networked devices

lastcheckin
string <date-time>

Timestamp for the last time the device reported a heartbeat to the platform

serialnumber
string

Serial number of the device

{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "os": {
    },
  • "apps": [
    ],
  • "imei": "615022756680303",
  • "name": "Store 123 Device #2",
  • "self": "string",
  • "group": {
    },
  • "family": "D03",
  • "battery": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "connection": {
    },
  • "lastcheckin": "2019-08-24T14:15:22Z",
  • "serialnumber": "21BC01CF8DFF"
}

Project

A Project is a collection of apps and configuration that can be deployed to a device.

id
string

Unique ID of project

name
string

Name of project

apiLevel
integer (APILevel)
Enum: 23 25 27 30
createdAt
string <RFC3339>

Timestamp of when the project was created

updatedAt
string <RFC3339>

Timestamp of when the project was last updated

description
string

Description of project

deviceFamily
string (DeviceFamily)
Enum: "D03" "F07" "D450" "D450A" "D450A1" "D450B" "C210" "F210" "F450" "G430" "G450" "I3399A" "A4100" "D215"
{
  • "id": "string",
  • "name": "string",
  • "apiLevel": 23,
  • "createdAt": "string",
  • "updatedAt": "string",
  • "description": "string",
  • "deviceFamily": "D03"
}