Skip to content

Folders

Folder Data Structure

A folder is a structural component that is used to organize and group devices.

Folder nesting

When displayed in a nested list or a tree component, folders will be organized in a nested way. For example, a folder with the name Sensors / Weather will be nested under a folder called Sensors. If you want to utilize folders to hierachically structure your devices, please make sure to use the slash /, surrounded by a space `` on either side.

For all devices under a certain folder, packets or readings can be retrieved.

In responses, a folder looks like this:

{
  "updated_at": "2017-01-01T00:00:01.000000",
  "slug": "active-sensors-humidity-pro",
  "profile_data":[
    {
      "updated_at":"2017-08-09T06:33:57.181488",
      "profile_id":"3e0db966-ed82-4f1d-96d0-08d4f9696abe",
      "profile":{
         "updated_at":"2017-08-09T06:13:39.596302",
         "slug":"example_profile",
         "name":"Beispiel Profil",
         "mandate_id":"50e032fb-964f-440d-9b9a-47870667373c",
         "limit_to":"none",
         "inserted_at":"2017-08-09T06:13:39.596295",
         "id":"3e0db966-ed82-4f1d-96d0-08d4f9696abe",
         "fields":[
            {
               "type":"string",
               "required":false,
               "name":"name",
               "min":null,
               "max":null,
               "id":"11ad6ef4-645b-47f0-a552-4b09f28e93a7",
               "format":null,
               "display":"Name"
            }
         ]
      },
      "inserted_at":"2017-08-09T06:33:57.181477",
      "device_id":"a70a234e-d186-4ca8-836b-74816738939e",
      "data":{
         "name":"Example Name"
      }
    }
  ],
  "name": "active_sensors / humidity / pro",
  "mandate_id": "50e032fb-964f-440d-9b9a-47870667373c",
  "inserted_at": "2017-01-01T00:00:01.000000",
  "id": "9e5121d8-dbb7-42d9-ba46-1bc95af3a350",
  "fields": {
    "example_profile": {
      "name":"Example Name"
    }
  },
  "description": "Grouping for professional humidity sensors",
  "default_layers_id": null,
  "default_graph_preset_id": null,
  "color_hue": 31
}
Key Example Description
name active_sensors / humidity / pro Name of the folder. Make sure you correctly use nesting.
slug active-sensors-humidity-pro URL-compatible name-based slug
description Grouping for professional humidity sensors Description text for the folder
id 9e5121d8-dbb7-42d9-ba46-1bc95af3a350 Unique folder ID (UUID4)
profile_data [ ... profile_data ... ] An array of profile_data entries with connected profiles (since v2.4.0)
fields {"profile_name": {"key": "value"}} JSON Object for accessing the values from connected profiles (since v2.4.0)
color_hue 31 Hue color value (0 to 359) for the display color in the frontend
mandate_id 50e032fb-964f-440d-9b9a-47870667373c Reference to the mandate this device belongs to
updated_at 2017-01-01T00:00:01.000000 Date of the last change to the folder
inserted_at 2017-01-01T00:00:01.000000 Date of the creation to the folder

List all Folders

Method: GET, Endpoint: /tags

To filter with a selector, use this endpoint:

/tags/by-:type/:identifier/

Example Request

GET https://element-iot.com/api/v1/tags?auth=46cb688e2c0b468e26e914235d4b73ea

Example Response

{
  "status": 200,
  "retrieve_after_id": "a70a234e-d186-4ca8-836b-74816738939e",
  "ok": true,
  "body": [
    // Contains an array of folders
  ]
}

This endpoint returns a paginated list of folders.

If you want to configure the sort order or restrict the results to a specific time interval, please refer to the Pagination section of this documentation.

The data from profiles is not included by default in the folder listing. Adding the profile and data can be done using the parameter &with_profile=1 (since v2.4.0).

Filtering

By using selectors, the folder list can be filtered by certain identifiers.

The root schema of the filter is a folder.

Show a single Folder

Method: GET, Endpoint: /tags/:tag_id

The folder ID may be either the id or the slug of the folder.

Example Request

GET https://element-iot.com/api/v1/tags/9e5121d8-dbb7-42d9-ba46-1bc95af3a350?auth=46cb688e2c0b468e26e914235d4b73ea

GET https://element-iot.com/api/v1/tags/active-sensors-humidity-pro?auth=46cb688e2c0b468e26e914235d4b73ea

Example Response

{
  "status": 200,
  "ok": true,
  "body": {
    // Contains the folder
  }
}

Create a new Folder

Method: POST, Endpoint: /tags

The folder ID may be either the id or the slug of the folder.

Example Request

POST https://element-iot.com/api/v1/tags?auth=46cb688e2c0b468e26e914235d4b73ea
{
  "tag": {
    "name": "New Folder Name",
    "type": "sensor"
  }
}

Example Response

{
  "status": 200,
  "ok": true,
  "body": {
    // Contains the new folder
  }
}

Parameters

Encapsulate all parameters to be changed in a folder object in the request body.

Edit single Folder

Method: PUT or PATCH, Endpoint: /tags/:tag_id

The folder ID may be either the id or the slug of the folder.

Example Request

PUT https://element-iot.com/api/v1/tags/active-sensors-humidity-pro?auth=46cb688e2c0b468e26e914235d4b73ea
{
  "tag": {
    "name": "New Name",
    "color_hue": 40
  }
}

Example Response

{
  "status": 200,
  "ok": true,
  "body": {
    // Contains the changed folder
  }
}

Parameters

Encapsulate all parameters to be changed in a folder object in the request body.

Delete single Folder

Method: DELETE, Endpoint: /tags/:tag_id

The folder ID may be either the id or the slug of the folder.

Example Request

DELETE https://element-iot.com/api/v1/tags/active-sensors-humidity-pro?auth=46cb688e2c0b468e26e914235d4b73ea

Example Response

{
  "status": 204,
  "ok": true,
  "body": {
    "deleted": true
  }
}

Show Devices for Folder

Method: GET, Endpoint: /tags/:tag_id/devices

The folder ID may be either the id or the slug of the folder.

Example Request

GET https://element-iot.com/api/v1/tags/active-sensors-humidity-pro/devices?auth=46cb688e2c0b468e26e914235d4b73ea

Example Response

{
  "status": 200,
  "ok": true,
  "body": {
    // Contains a list of the devices attached to the folder
  }
}

This endpoint returns a paginated list of devices belonging to this particular folder. Please refer to the devices documentation for the contents of the response.

If you want to configure the sort order or restrict the results to a specific time interval, please refer to the Pagination section of this documentation.

The data from profiles is not included by default in the device listing. Adding the profile and data can be done using the parameter &with_profile=1 (since v2.4.0).

You can preload between 0 and 20 of the last readings of each device by passing the parameter last_readings=x where x is the desired amount of readings. If a value greater than 0 is passed, each device will have an additional field called last_readings which contains a list of the readings, ordered from newest to oldest.

Show Packets for Folder

Method: GET, Endpoint: /tags/:tag_id/packets

Streaming variant: /tags/:tag_id/packets/stream - read more about streaming

Example Request

GET https://element-iot.com/api/v1/tags/active-sensors-humidity-pro/packets?auth=46cb688e2c0b468e26e914235d4b73ea

Example Response

{
  "status": 200,
  "ok": true,
  "body": {
    // Contains a list of the packets attached to the folder
  }
}

The folder ID may be either the id or the slug of the folder.

The optional parameter packet_type can be used to filter packets by type. For example when only up packets are needed.

The sorting is fixed to transceived_at and can not be changed.

This endpoint returns a paginated list of packets for all devices belonging to this particular folder. Please refer to the packets documentation for the contents of the response.

If you want to restrict the results to a specific time interval, please refer to the Pagination section of this documentation.

Show Readings for Folder

Method: GET, Endpoint: /tags/:tag_id/readings

Streaming variant: /tags/:tag_id/readings/stream - read more about streaming

Parameters

Query Parameter Description
auth
String *****
API Key or JWT
retrieve_after
UUID
To go to the next page, pass the ID of the last reading from the result list here.
Read more about pagination
sort
measured_at
Column to sort the readings by
(default measured_at)
sort_direction
asc or desc
Switch the sort direction
(default desc)
limit
Integer 1-100
Control how many readings are loaded per page
(default 10)
before
ISO8601
Only show readings measured before this date
after
ISO8601
Only show readings measured after this date
filter
AbacusSql
Expression that filters the readings.
The root schema of the filter is a reading.

Example Request

GET https://element-iot.com/api/v1/tags/active-sensors-humidity-pro/readings?auth=46cb688e2c0b468e26e914235d4b73ea

Example Response

{
  "status": 200,
  "ok": true,
  "body": {
    // Contains a list of the readings attached to the folder
  }
}

The folder ID may be either the id or the slug of the folder.

The sorting is fixed to measured_at and can not be changed.

This endpoint returns a paginated list of readings for all devices belonging to this particular folder. Please refer to the readings documentation for the contents of the response.

If you want to restrict the results to a specific time interval, please refer to the Pagination section of this documentation.

Websocket

The packets and readings of all devices in a tag can be pushed using a websocket.