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
}

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
  }
}

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
  }
}

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¶

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.