Mason Docs

Group API

Use Group APIs to retrieve information about device groups in the Mason Platform.

Group Model

The following is a sample group model, represented in JSON

{
    "createdAt": "2019-04-15T21:14:31.369Z",
    "description": "This is a test group.",
    "name": "Test Group",
    "self": "/v1/default/group/Test%20Group"
}

GET Group

https://api.bymason.com/v1/default/group/{name}

Retrieves a single Group model in your fleet.

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/group/$GROUP_NAME

POST Group

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

Creates a new Group in the Mason Platform.

Required API key scope(s)

  • fleet:admin

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

Request body

NameTypeDescription
namestringGroup names should be semantic, and represent what your devices are purposefully deployed for. Names must only contain [a-z], [A-Z], [0-9], underscore, and dashes
descriptionstringlimit 300 characters

Sample request(s)

$ curl
-H "Authorization: basic $API_KEY"
-d '{
"description": "Description of my group",
"name": "TestGroup"
}'
api.bymason.com/v1/default/group

DELETE Group

https://api.bymason.com/v1/default/group/{name}

Deletes a Group in the Mason Platform. The Group must not have any devices in it, or else the operation will fail.

Required API key scope(s)

  • fleet:admin

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

Sample request(s)

$ curl -H "Authorization: basic $API_KEY" -X "DELETE" api.bymason.com/v1/default/group/$GROUP_NAME

GET Groups

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

Fetches a page of Group models in your fleet.

Required API key scope(s)

  • fleet:read

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

Optional request parameters

ParametersDescriptionExample
limitLimit to number of devices returned/v1/default/group?limit=10
beforeRequest the previous page/v1/default/group?before=40052b21-211c-4d1e-9e81-fec7e2f64582
afterRequest the next page/v1/default/group?after=40052b21-211c-4d1e-9e81-fec7e2f64582

Sample request(s)

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

GET Group Devices

https://api.bymason.com/v1/default/group/{name}/list

Retrieves a paged list of Device models that are related to the given Group.

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/group/$GROUP_NAME/list

Sample response body

For more information on the Device models returned from this endpoint, visit our Device model documentation

{
  data: [
      {
          id: 'device-01',
          name: 'TestDevice001',
          ...
      },
      ...
  ]
}

GET Group Deployments

https://api.bymason.com/v1/default/group/{name}/deployment

Retrieves a list of deployments that have been published to the given Group.

This list is NOT paginated and can get very large.

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/group/$GROUP_NAME/deployment

Sample response body

Deployments returned from this endpoint are represented in a list of the following models.

NameTypeDescription
namestringThe name of the 'artifact' that was deployed
typestringThe type of the 'artifact' that was deployed - os, config, or apk
versionstringThe version of the 'artifact' that was deployed
createdAtstringTimestamp in the ISO 8601 format YYYY-MM-DDTHH:mm:ss.sssZ
group_namestringThe group name that this deployment relates to
uuidstringDeployment ID
[
    {
        "name":"f450",
        "type":"config",
        "version":"17",
        "createdAt":"2020-06-08T17:59:28.299Z",
        "group_name":"f450",
        "uuid":"40052b21-211c-4d1e-9e81-fec7e2f64582"
    },
    ...
]

POST Group devices

https://api.bymason.com/v1/default/group/{name}/move

Use this endpoint to move Devices in to your Group. To move a Device out of your Group, move it to a different group.

Required API key scope(s)

  • fleet:admin

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

Optional request parameters

ParametersDescriptionExample
validateonlyValidate if the move is allowed/v1/default/group?validateonly=true

Using this endpoint with the parameter validateonly=true will return with one of two results...

  1. An HTTP status code 400, which means the move you are attempting is not valid. The result should include an error type and context that explains why the move failed.
  2. An HTTP status code 200, which means the move you are attempting will succeed. The result should include the following response body
NameTypeDescription
willUpdatebooleanSet to true if the target group has received a project deployment and the devices will automatically download and install the update when they are moved
willWipebooleanSet to true if the devices will automatically wipe when they are moved
emptyGroupbooleanSet to true if the target group has not received a project deployment yet
newProjectstringThe most recent project deployed to the target group. Will be undefined if emptyGroup === true
newVersionstringThe version of the most recent project deployed to the target group
{
    "willUpdate":true,
    "willWipe":false,
    "emptyGroup":false,
    "newProject":"ypr-test-handheld",
    "newVersion":"13"
}

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/group/$GROUP_NAME/move