Docs

Appearance

Open console

Reference

Asset Groups

REST API reference for Asset Groups: manage asset groups, their properties and the locations of their assets. 17 operations.

Reference9 min read

For the base URL, authentication and errors, see the REST API overview.

GET /v1/users/{user}/groups ​

  • Request: GET /v1/users/{user}/groups
  • Operation: ListGroups
  • Operation ID: Group_List
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v1/users/YOUR_USER/groups' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

Response example (200)

json
[
  {
    "group": "madrid_line_2",
    "name": "Line 2",
    "parent": "madrid_plant"
  },
  {
    "description": "Devices installed in the Madrid plant",
    "group": "madrid_plant",
    "name": "Madrid plant"
  }
]

POST /v1/users/{user}/groups ​

  • Request: POST /v1/users/{user}/groups
  • Operation: CreateGroup
  • Operation ID: Group_Create
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes

Request body (application/json, required)

An asset group is where or whose a device is (a site, a customer, a building). Groups nest through 'parent'; devices join one with their asset_group field and inherit its properties. Project members can be limited to some groups.

FieldTypeRequiredConstraintsDescription
descriptionstringno
groupstringyesPattern: ^[a-zA-Z0-9_-]{1,32}$A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
namestringno
parentstringnoPattern: ^[a-zA-Z0-9_-]{1,32}$A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.

Example request: Area inside a site

bash
curl -X POST 'https://YOUR_SERVER/v1/users/YOUR_USER/groups' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "group": "madrid_line_2",
  "name": "Line 2",
  "parent": "madrid_plant"
}'

Example body: Site

json
{
  "description": "Devices installed in the Madrid plant",
  "group": "madrid_plant",
  "name": "Madrid plant"
}

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v1/users/{user}/groups/{group} ​

  • Request: GET /v1/users/{user}/groups/
  • Operation: ReadGroupConfig
  • Operation ID: Group_ReadConfig
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
grouppathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v1/users/YOUR_USER/groups/YOUR_GROUP' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

Response example (200, Area inside a site)

json
{
  "group": "madrid_line_2",
  "name": "Line 2",
  "parent": "madrid_plant"
}

Response example (200, Site)

json
{
  "description": "Devices installed in the Madrid plant",
  "group": "madrid_plant",
  "name": "Madrid plant"
}

PUT /v1/users/{user}/groups/{group} ​

  • Request: PUT /v1/users/{user}/groups/
  • Operation: UpdateGroup
  • Operation ID: Group_Update
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
grouppathstringyes

Request body (application/json, required)

FieldTypeRequiredConstraintsDescription
descriptionstringno
namestringno

Example request: Rename

bash
curl -X PUT 'https://YOUR_SERVER/v1/users/YOUR_USER/groups/YOUR_GROUP' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "description": "North building",
  "name": "Madrid plant - north"
}'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

DELETE /v1/users/{user}/groups/{group} ​

  • Request: DELETE /v1/users/{user}/groups/
  • Operation: DeleteGroup
  • Operation ID: Group_Delete
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
grouppathstringyes

Example request

bash
curl -X DELETE 'https://YOUR_SERVER/v1/users/YOUR_USER/groups/YOUR_GROUP' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v1/users/{user}/groups/{group}/clone ​

  • Request: GET /v1/users/{user}/groups/{group}/clone
  • Operation: CloneGroupConfig
  • Operation ID: Group_CloneConfig
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
grouppathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v1/users/YOUR_USER/groups/YOUR_GROUP/clone' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

POST /v1/users/{user}/groups/{group}/clone ​

  • Request: POST /v1/users/{user}/groups/{group}/clone
  • Operation: CloneGroup
  • Operation ID: Group_Clone
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
grouppathstringyes

Request body (application/json, required)

FieldTypeRequiredConstraintsDescription
descriptionstringnoMaximum length: 255A brief description of the resource, providing context or additional information, limited to 255 characters.
enabledbooleanno
groupstringyesPattern: ^[a-zA-Z0-9_-]{1,32}$A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
namestringnoMaximum length: 255The name of the resource, limited to 255 characters. It can include any character.

Example request: Copy with a new id

bash
curl -X POST 'https://YOUR_SERVER/v1/users/YOUR_USER/groups/YOUR_GROUP/clone' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "group": "copy_of_group"
}'

Example body: Copy with name and description

json
{
  "description": "Same configuration as the original, for production line 2",
  "group": "line_2_group",
  "name": "Line 2 copy"
}

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v1/users/{user}/groups/{group}/locations ​

  • Request: GET /v1/users/{user}/groups/{group}/locations
  • Operation: ReadAssetsLocations
  • Operation ID: Group_ReadAssetsLocations
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
grouppathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v1/users/YOUR_USER/groups/YOUR_GROUP/locations' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

PUT /v1/users/{user}/groups/{group}/projects ​

  • Request: PUT /v1/users/{user}/groups/{group}/projects
  • Operation: UpdateGroupProjects
  • Operation ID: Group_UpdateProjects
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
grouppathstringyes

Request body (application/json, required)

FieldTypeRequiredConstraintsDescription
(body)array of stringnoProjects the resource belongs to, as <owner>@<project> ids. Replaces the whole list: read the current one first to add or remove a single project; [] removes it from every project.

Example request: No projects

bash
curl -X PUT 'https://YOUR_SERVER/v1/users/YOUR_USER/groups/YOUR_GROUP/projects' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '[]'

Example body: One project

json
[
  "YOUR_USER@greenhouse"
]

Example body: Two projects

json
[
  "YOUR_USER@greenhouse",
  "YOUR_USER@maintenance"
]

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v1/users/{user}/groups/{group}/properties ​

  • Request: GET /v1/users/{user}/groups/{group}/properties
  • Operation: ListGroupProperties
  • Operation ID: Group_ListProperties
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
grouppathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v1/users/YOUR_USER/groups/YOUR_GROUP/properties' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

Response example (200)

json
[
  {
    "created": 1792263090708,
    "description": "Sampling and alert thresholds",
    "modified": 1792263090708,
    "name": "Settings",
    "property": "settings",
    "type": "configuration",
    "value": {
      "alerts": true,
      "interval": 60,
      "max_temperature": 28.5
    }
  },
  {
    "created": 1792263090708,
    "modified": 1792263090708,
    "name": "Location",
    "property": "location",
    "value": {
      "lat": 40.4168,
      "lon": -3.7038
    }
  },
  {
    "created": 1792263090708,
    "modified": 1792263090708,
    "name": "Calibration",
    "perm": {
      "readOnly": [
        "member"
      ]
    },
    "property": "calibration",
    "value": {
      "gain": 1.02,
      "offset": -0.4
    }
  },
  {
    "created": 1792263090708,
    "modified": 1792263090708,
    "name": "Dashboard",
    "property": "dashboard",
    "value": {
      "source": "url",
      "url": "/v1/users/YOUR_USER/storages/fleet_app/files/"
    }
  }
]

POST /v1/users/{user}/groups/{group}/properties ​

  • Request: POST /v1/users/{user}/groups/{group}/properties
  • Operation: CreateGroupProperty
  • Operation ID: Group_CreateProperty
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
grouppathstringyes

Request body (application/json, required)

The body matches one of these 2 variants.

Variant 1

FieldTypeRequiredConstraintsDescription
(body)array of objectno
(body)[].descriptionstringnoMaximum length: 255A brief description of the resource, providing context or additional information, limited to 255 characters.
(body)[].formobjectno
(body)[].form.fieldsanyyes
(body)[].namestringnoMaximum length: 255The name of the resource, limited to 255 characters. It can include any character.
(body)[].permobjectno
(body)[].perm.hiddenarray of stringnoUnique items
(body)[].perm.readOnlyarray of stringnoUnique items
(body)[].propertystringyesPattern: ^[a-zA-Z0-9_-]{1,32}$A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
(body)[].typestringnoOne of: ``, configuration
(body)[].valueanyyes

Variant 2: Property Create. Schema for creating a property

Schema for creating a property

FieldTypeRequiredConstraintsDescription
descriptionstringnoMaximum length: 255A brief description of the resource, providing context or additional information, limited to 255 characters.
formobjectno
form.fieldsanyyes
namestringnoMaximum length: 255The name of the resource, limited to 255 characters. It can include any character.
permobjectno
perm.hiddenarray of stringnoUnique items
perm.readOnlyarray of stringnoUnique items
propertystringyesPattern: ^[a-zA-Z0-9_-]{1,32}$A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
typestringnoOne of: ``, configuration
valueanyyes

Example request: Configuration value

bash
curl -X POST 'https://YOUR_SERVER/v1/users/YOUR_USER/groups/YOUR_GROUP/properties' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "description": "Sampling and alert thresholds",
  "name": "Settings",
  "property": "settings",
  "type": "configuration",
  "value": {
    "alerts": true,
    "interval": 60,
    "max_temperature": 28.5
  }
}'

Example body: Location

json
{
  "name": "Location",
  "property": "location",
  "value": {
    "lat": 40.4168,
    "lon": -3.7038
  }
}

Example body: Read-only for project members

json
{
  "name": "Calibration",
  "perm": {
    "readOnly": [
      "member"
    ]
  },
  "property": "calibration",
  "value": {
    "gain": 1.02,
    "offset": -0.4
  }
}

Example body: Url dashboard of the resource

json
{
  "name": "Dashboard",
  "property": "dashboard",
  "value": {
    "source": "url",
    "url": "/v1/users/YOUR_USER/storages/fleet_app/files/"
  }
}

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v1/users/{user}/groups/{group}/properties/{property} ​

  • Request: GET /v1/users/{user}/groups/{group}/properties/
  • Operation: ReadGroupProperty
  • Operation ID: Group_ReadProperty
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
grouppathstringyes
propertypathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v1/users/YOUR_USER/groups/YOUR_GROUP/properties/YOUR_PROPERTY' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

PUT /v1/users/{user}/groups/{group}/properties/{property} ​

  • Request: PUT /v1/users/{user}/groups/{group}/properties/
  • Operation: UpdateGroupProperty
  • Operation ID: Group_UpdateProperty
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
grouppathstringyes
propertypathstringyes

Request body (application/json, required)

Schema for updating a property

FieldTypeRequiredConstraintsDescription
descriptionstringnoMaximum length: 255A brief description of the resource, providing context or additional information, limited to 255 characters.
formobjectno
form.fieldsanyyes
namestringnoMaximum length: 255The name of the resource, limited to 255 characters. It can include any character.
permobjectno
perm.hiddenarray of stringnoUnique items
perm.readOnlyarray of stringnoUnique items
propertystringnoPattern: ^[a-zA-Z0-9_-]{1,32}$A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
typestringnoOne of: ``, configuration
valueanyyes

Example request: Hide from project members

bash
curl -X PUT 'https://YOUR_SERVER/v1/users/YOUR_USER/groups/YOUR_GROUP/properties/YOUR_PROPERTY' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "perm": {
    "hidden": [
      "member"
    ]
  },
  "value": "internal note"
}'

Example body: Replace the value

json
{
  "value": {
    "alerts": true,
    "interval": 30,
    "max_temperature": 27
  }
}

Example body: Value, name and description

json
{
  "description": "Faster sampling during commissioning",
  "name": "Settings",
  "value": {
    "alerts": false,
    "interval": 10,
    "max_temperature": 28.5
  }
}

Responses

StatusDescription
200ok
401unauthorized
403forbidden

PATCH /v1/users/{user}/groups/{group}/properties/{property} ​

  • Request: PATCH /v1/users/{user}/groups/{group}/properties/
  • Operation: UpdateGroupProperty
  • Operation ID: Group_PatchProperty
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
grouppathstringyes
propertypathstringyes

Request body (application/json, required)

The body matches one of these 2 variants.

Variant 1

FieldTypeRequiredConstraintsDescription
valueanyyes

Variant 2

FieldTypeRequiredConstraintsDescription
*anyno

Example request: Change some fields of the value

bash
curl -X PATCH 'https://YOUR_SERVER/v1/users/YOUR_USER/groups/YOUR_GROUP/properties/YOUR_PROPERTY' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "value": {
    "interval": 30
  }
}'

Example body: Flattened fields

json
{
  "value.alerts": false,
  "value.max_temperature": 27
}

Responses

StatusDescription
200ok
401unauthorized
403forbidden

DELETE /v1/users/{user}/groups/{group}/properties/{property} ​

  • Request: DELETE /v1/users/{user}/groups/{group}/properties/
  • Operation: DeleteGroupProperty
  • Operation ID: Group_DeleteProperty
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
grouppathstringyes
propertypathstringyes

Example request

bash
curl -X DELETE 'https://YOUR_SERVER/v1/users/YOUR_USER/groups/YOUR_GROUP/properties/YOUR_PROPERTY' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v1/users/{user}/groups/{group}/properties/{property}/clone ​

  • Request: GET /v1/users/{user}/groups/{group}/properties/{property}/clone
  • Operation: CloneGroupPropertyConfig
  • Operation ID: Group_ClonePropertyConfig
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
grouppathstringyes
propertypathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v1/users/YOUR_USER/groups/YOUR_GROUP/properties/YOUR_PROPERTY/clone' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

POST /v1/users/{user}/groups/{group}/properties/{property}/clone ​

  • Request: POST /v1/users/{user}/groups/{group}/properties/{property}/clone
  • Operation: CloneGroupProperty
  • Operation ID: Group_CloneProperty
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
grouppathstringyes
propertypathstringyes

Request body (application/json, required)

FieldTypeRequiredConstraintsDescription
descriptionstringnoMaximum length: 255A brief description of the resource, providing context or additional information, limited to 255 characters.
enabledbooleanno
namestringnoMaximum length: 255The name of the resource, limited to 255 characters. It can include any character.
propertystringyesPattern: ^[a-zA-Z0-9_-]{1,32}$A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.

Example request: Copy with a new id

bash
curl -X POST 'https://YOUR_SERVER/v1/users/YOUR_USER/groups/YOUR_GROUP/properties/YOUR_PROPERTY/clone' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "property": "copy_of_property"
}'

Example body: Copy with name and description

json
{
  "description": "Same configuration as the original, for production line 2",
  "name": "Line 2 copy",
  "property": "line_2_property"
}

Responses

StatusDescription
200ok
401unauthorized
403forbidden