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

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

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

Sample response body

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

[
    {
        "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. A maximum of 500 devices may be moved at a time.

Required API key scope(s)

• fleet:admin

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

Optional request parameters

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

{
    "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