Overview
Before a KOLO™ device can be added to your account, your account must be setup with tags such as buildings, floors and rooms.
GET /metadata
The GET /metadata endpoint provides hierarchical metadata information about KOLO™ IoT devices, including account, building, floor, room, and device location details. This data enables developers to create a structured view of the account’s physical layout and supports applications like facility maps, digital twins, and location-based management systems.
Recommended Polling Interval: Metadata updates are infrequent, so polling every hour is sufficient unless metadata changes (such as added, modified, or deleted buildings, floors, rooms, or device locations) are expected.
Request
Query Parameters
All query parameters are optional and can be used to filter metadata results based on the account structure.
| Parameter | Type | Description |
|---|---|---|
| building_id | string | Unique identifier for the building where the device is located |
| floor_id | string | Unique identifier for the floor where the device is located |
| room_id | string | Unique identifier for the room where the device is located |
| device_location_id | integer | Unique identifier for the device’s location within the room |
| device_type | string | Category/type of the device (e.g., tissue, sanitizer) |
| limit | integer | Count of records to be fetched in a request with offset pagination. limit would fetch the specified list of records for the rooms count instead of entire set of records. If not specified, defaults to 100 |
| offset | integer | Count of records to be ignored from the start. offset is used along with limit. If not specified, defaults to 0 |
Response
Status Code
200 - Successful execution of the request.
Error Codes
| Status Code | Error Message | Description |
|---|---|---|
| 400 | Bad Request | Invalid or malformed request parameters were provided |
| 401 | Unauthorized | Missing or invalid authorization token |
| 403 | Forbidden | API key or authorization header is missing or invalid |
| 404 | Not Found | Resource specified cannot be found |
| 500 | Internal Server Error | An unexpected error occurred on the server |
Response Attributes
The response contains metadata detailing the physical layout of a KOLO™ account, organized hierarchically by account, building, floor, room, and device location.
| Attribute | Type | Description |
|---|---|---|
| total_count | integer | The total number of rooms that could be retrieved |
| next | string | URL to retrieve the next page of rooms |
| prev | string | URL to retrieve the previous page of rooms |
| account_name | string | Name of the account for which metadata is retrieved |
| account_id | string | Account Id for which metadata is retrieved |
| metadata | array[object] | List of metadata tags, organized by account, building, floor, room, and device locations |
| building_id | string | Building id for the retrieved room |
| building_name | string | Building name for the retrieved room |
| floor_id | string | Floor id for the retrieved room |
| floor_name | string | Floor name for the retrieved room |
| room_id | string | Unique identifier for retrieved room |
| room_name | string | Name or label for the retrieved room |
| device_locations | array[object] | List of device location details within the room |
| location_id | string | Unique identifier for the device’s location within the room |
| location_name | string | Name or label for the device location |
| type | string | Category/type of the device (e.g., tissue, soap) |
Sample Response
{
"total_count": 1878, // total count of objects(room) in a list
"next": "url for fetching next page",
"prev": "url for fetching previous page",
"account_name": "Account A",
"account_id": "8958397",
"metadata" : [
{
"floor_name": "Floor A",
"floor_id": "8958397",
"building_name": "Building A",
"building_id": "8958397",
"room_name": "Room A",
"room_id": "8958397",
"device_locations": [
{
"location_id": "979672",
"location_name": "Device Location 1",
"type": "Soap"
},
{
"location_id": "979673",
"location_name": "Device Location 2",
"type": "Tissue"
}
]
}
]
}