Devices
Inspecting Devices and metadata in the Ardexa Cloud
Viewing devices
To get a list of devices in a workgroup, make a GET request against the Devices endpoint:
GET mycloud.ardexa.com/api/v1/devices/<workgroupId>This will return a list of all devices in the workgroup, fully populated with their current device metadata.
Alternatively, you can issue a GET against an individual device's UUID:
GET mycloud.ardexa.com/api/v1/devices/<workgroupId>/<deviceId>Device Groups
Device Groups can be used to restrict users to a subset of the devices in a workgroup. To retrieve a list of Device Groups in a workgroup, call:
GET mycloud.ardexa.com/api/v1/orgs/<workgroupId>/device-groupsTo get a list of devices in a specific Device Group, pass the Device Group's ID as a query parameter:
GET mycloud.ardexa.com/api/v1/devices/<workgroupId>?devGroup=<devGroupId>This option is only available to users and API tokens that are not restricted by Device Group membership.
Accessing device metadata
Device metadata is stored against the meta top-level property of the device. meta has a number of top-level properties containing lists of scenarios as described in Agent -> Manual Configuration and displayed in Devices -> Manual Configuration in the Ardexa Cloud.
The scenario types provided as of Agent version 2.4.1 are:
run: execute a task at a defined frequency / schedule. Optionally capture the output as an event to send to the Ardexa Cloud
tail: watch a text file for new lines. These are captured as events and sent to the Ardexa Cloud. This corresponds to the 'Capture' tab on the Device -> Manual Config page in the app
watch: watch a file for changes. When one is detected, send an event to the cloud, optionally attaching the file content
unix_socket: listens for events on a specified unix socket. These are captured and sent to the cloud
dynamic: tail scenarios detected dynamically by the Ardexa agent, see Dynamic Mapping below
External metadata scenarios are optionally stored separate to the device's configuration, within the settings.externalMeta property. These link data ingested to the cloud from a non-agent source, such as an external API, to the device.
Metadata terminology
Scenario: an individual unit of work performed by the agent. This usually involves executing a command at a specified interval or watching a file for changes. See Scenarios for more information. An important rule is that within a device's configuration, the combination of each scenario's table and source must be unique.
Static configuration: run, tail, watch, unix_socket and external define statically configured scenarios derived from the ardexa.yaml configuration file on the device. This was the first metadata configuration scheme implemented in the Ardexa Cloud.
Dynamic mapping: dynamic scenarios, introduced in agent version 2.3.0 are populated by the Ardexa agent. The agent watches specific file system locations on the device for dynamic run and dynamic tail scenarios, typically executable files in /opt/ardexa/run and latest.csv files in/opt/ardexa/logs respectively. This scheme scales well with large device configurations and is heavily used by the Machine Plugins system. For more information, see Dynamic Mapping.
Accessing fields
Where a scenario has an expect type of csv, the agent expects to receive a CSV-formatted record containing one or more fields. This record is transformed into an event which is sent to the Ardexa Cloud. The set of fields is determined by the fields property of the scenario.
An individual field has the following schema:
There are three variants of field definition used in the Ardexa Cloud:
Hydrated metadata
If the fields property of a scenario is an array, the contents of the array define the exact set of fields collected by that scenario. When all scenarios in a device's configuration contain fields arrays we refer to it as "Hydrated" metadata. For larger device configurations with many scenarios collecting identical fields this results in many redundant field definitions.
Example:
Compact metadata
If the fields property contains a string without a period (.), the scenario is using a compact fields reference. The value of fields will resolve to a top-level property of the device's meta. This top-level property will contain an array of fields collected by the scenario.
Example:
Dynamic compact metadata
If the fields property contains a string with a single period (.), the scenario is using a dynamic compact fields reference. The format of the fields property will be <table>.<source> . The table and source refer to a scenario within the current scenario type (eg. dynamic) that contains the actual fields array used by both scenarios.
Note that the actual scenario that contains the field definition is set dynamically by the Ardexa Agent, so may change when a device's metadata is updated.
Example:
Viewing Device & Source General Information
Device & Source General Information (as displayed in Devices -> General Info in the app, or maintained in the Admin -> Workgroup -> Metadata section) is stored as a device setting on each device in a workgroup. Look-ups for this information must be retrieved from the Workgroup's deviceInfoKeys and sourceInfoKeys settings. Each id in these settings corresponds to the ID of a device setting, as returned in the settings property of the GET device endpoint.
Source-level metadata is stored as a map, keyed by source name.
Accessing latest values
Latest values logged to the Ardexa Cloud can be accessed via the latest values endpoints.
If the "Latest Values Cache" addon is enabled in the workgroup, the "cached latest values" endpoint can be used to retrieve the latest values from an arbitrary set of data streams in the workgroup.
Retrieves the most recent data value per device (or per source) for all accessible devices, optionally grouped by source or device. Supports filtering by source and specific fields. The search window defaults to the last 24 hours; supply startTime/endTime or days to look further back, which is how a last-known value is resolved for devices that have been offline.
There are four ways to read a latest value; this one covers every device at once. For one device use /devices/{orgName}/{device}/latestValues, for one named stream use /devices/{orgName}/{device}/latest/{stream}, and for a fixed set of streams read straight from cache use /devices/{orgName}/device/cachedLatestValues.
An Ardexa API token, sent as Authorization: Bearer <token>.
Workgroup ID
Name of the data table to query
Filter results by specific data source
Filter to only include records where this field exists. Accepts a single field or a comma-separated list, in which case every listed field must exist.
Require each field named by field to be non-zero as well as present. Used for last-known-position lookups, where a zero coordinate means "no fix" rather than a location.
falseReturn only the fields named by field (plus event_time) instead of the whole record. Requires field. Off by default, so existing callers keep receiving full records.
falseHow to group the results - by source or by device
sourcePossible values: Start of the search window (ISO 8601). Must be supplied together with endTime. Defaults to the start of the previous day.
End of the search window (ISO 8601). Must be supplied together with startTime.
Look back this many days instead of supplying an explicit window. Ignored when startTime/endTime are given, and clamped to 400 days.
Comma-separated device ids to narrow the query to, maximum 100. Always intersected with the caller's device group. Omit to include every device in scope.
Maximum number of devices to return, capped at 10000 (the default).
Latest values retrieved successfully
When groupBy=source - object keyed by deviceId, each containing an object keyed by source name with the latest record. When groupBy=device - object keyed by deviceId with the latest record directly
Invalid groupBy parameter (must be 'source' or 'device'), malformed startTime/endTime (lv001, lv002), invalid days (lv003), too many device ids (lv004), or invalid limit (lv005)
Missing, expired or invalid token
No access to this workgroup, or the token lacks the permission this endpoint needs
Internal server error
GET /api/v1/devices/{orgName}/device/latestValues?table=text HTTP/1.1
Host: app.ardexa.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"device1": {
"source1": {
"event_time": "2025-11-13T10:30:00Z",
"temperature": 25.5,
"humidity": 60
},
"source2": {
"event_time": "2025-11-13T10:31:00Z",
"voltage": 12.3
}
}
}Retrieves the most recent data values for a specific device, optionally grouped by source or device. Supports filtering by source and specific fields. The search window defaults to the last 24 hours; supply startTime/endTime or days to look further back.
For every device in the workgroup at once use /devices/{orgName}/device/latestValues. For a single named stream, /devices/{orgName}/{device}/latest/{stream} is cheaper.
An Ardexa API token, sent as Authorization: Bearer <token>.
Workgroup ID
Device ID
Name of the data table to query
Filter results by specific data source
Filter to only include records where this field exists. Accepts a single field or a comma-separated list, in which case every listed field must exist.
Require each field named by field to be non-zero as well as present. Used for last-known-position lookups, where a zero coordinate means "no fix" rather than a location.
falseReturn only the fields named by field (plus event_time) instead of the whole record. Requires field. Off by default, so existing callers keep receiving full records.
falseHow to group the results - by source or by device
sourcePossible values: Start of the search window (ISO 8601). Must be supplied together with endTime. Defaults to the start of the previous day.
End of the search window (ISO 8601). Must be supplied together with startTime.
Look back this many days instead of supplying an explicit window. Ignored when startTime/endTime are given, and clamped to 400 days.
Comma-separated device ids to narrow the query to, maximum 100. Always intersected with the caller's device group. Omit to include every device in scope.
Maximum number of devices to return, capped at 10000 (the default).
Latest values retrieved successfully
When groupBy=source - object keyed by deviceId containing an object keyed by source name with the latest record. When groupBy=device - object keyed by deviceId with the latest record directly
Invalid groupBy parameter (must be 'source' or 'device'), malformed startTime/endTime (lv001, lv002), invalid days (lv003), too many device ids (lv004), or invalid limit (lv005)
Missing, expired or invalid token
No access to this workgroup, or the token lacks the permission this endpoint needs
Device not found or not accessible in device group
Internal server error
GET /api/v1/devices/{orgName}/{device}/latestValues?table=text HTTP/1.1
Host: app.ardexa.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"device1": {
"source1": {
"event_time": "2025-11-13T10:30:00Z",
"temperature": 25.5,
"humidity": 60
},
"source2": {
"event_time": "2025-11-13T10:31:00Z",
"voltage": 12.3
}
}
}Get cached latest values for multiple device streams
Retrieves the most recent cached data values for the device streams you name, read straight from the cache rather than queried. Supports filtering by device group membership.
Requires the latest-values addon. Without it every request is refused with 403 — use /devices/{orgName}/device/latestValues instead, which queries the data directly and needs no addon.
An Ardexa API token, sent as Authorization: Bearer <token>.
Workgroup ID
Cached values retrieved successfully
Object keyed by deviceId, then by table, then by source, containing the requested field values
Bad request - Workgroup not found
Missing, expired or invalid token
No access to this workgroup, or the latest-values addon is not enabled for it
Internal server error
POST /api/v1/devices/{orgName}/device/cachedLatestValues HTTP/1.1
Host: app.ardexa.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 220
{
"streams": [
{
"deviceId": "device1",
"table": "sensors",
"source": "temp_sensor",
"field": "temperature",
"type": "decimal"
},
{
"deviceId": "device1",
"table": "sensors",
"source": "humidity_sensor",
"field": "humidity",
"type": "integer"
}
]
}{
"device1": {
"sensors": {
"temp_sensor": {
"temperature": 25.5
},
"humidity_sensor": {
"humidity": 60
}
}
}
}Last updated
Was this helpful?