The /loggers/* endpoints expose historical and live timeseries data over HTTP. They are the most heavily used part of the REST API — the Weble Cloud queries them to feed dashboards, sync site metadata, and forward write operations to remote gateways.
All endpoints described here require an authenticated session — see authentication.
GET /loggers/sitesReturn the list of sites known to the gateway. A site is one logical data source, identified by a unique id (typically the gateway's hardware address for the local box, or a remote box id when accessed through a log connector).
Query parameters:
| Param | Description |
|---|---|
connector |
Optional. Restrict the result to one or more logger connectors (string or array) |
group |
Optional. Restrict to connectors belonging to one or more groups |
detailed |
Optional. 1 to include name and metadata for each site, 0 (default) to return only ids |
Response (detailed=1):
[
{ "id" : "ab_cd_ef_01_02_03", "local" : true, "name" : "box_local_addresses" },
{ "id" : "site_remote_42", "name" : "Boiler room — Geneva" }
]
Example:
curl -b cookies.txt 'https://gateway.example.com/loggers/sites?detailed=1'
GET /loggers/dataThe main historical query endpoint. Returns timeseries values for one or more addresses, optionally aggregated.
Request body / query parameters:
| Field | Type | Description |
|---|---|---|
address |
string / array | One or more address keys to query |
start |
ISO date / millis | Start of the time window |
end |
ISO date / millis | End of the time window |
aggregate |
string | Optional. Aggregation interval — see units below. When set, returns (min, avg, max) per bucket |
streaming |
true / 1 |
If set, return NDJSON stream instead of a single JSON array |
connector |
string / array | Optional. Filter by logger connector |
group |
string / array | Optional. Filter by connector group |
Aggregation units for aggregate:
| Suffix | Unit | Example |
|---|---|---|
s |
seconds | 30s |
m |
minutes | 15m |
h |
hours | 1h |
d |
days | 1d |
w |
weeks | 1w |
o |
months | 1o |
y |
years | 1y |
Row format:
{
"id" : 23055,
"ts" : "2026-04-08T13:30:00.000Z",
"value" : 21.5,
"value_string" : "21.5°C",
"min" : 20.8,
"max" : 22.1
}
min and max are present only when aggregate is set.
Streaming response:
When streaming=true, the response is a text/plain body where each line is a complete JSON object representing one row, terminated by \r\n. The stream ends when the response closes. On error, the last line is {"error":"..."}.
Example — last 24 hours, 15-minute buckets, streamed:
curl -b cookies.txt 'https://gateway.example.com/loggers/data' \
-H 'Content-Type: application/json' \
-d '{
"address" : ["4/7/25", "4/7/26"],
"start" : "2026-04-07T00:00:00Z",
"end" : "2026-04-08T00:00:00Z",
"aggregate" : "15m",
"streaming" : true
}'
GET /loggers/siteDataReturn the complete site definition for a given site — addresses, last values, and metadata. Used by the cloud to sync site state in one round trip.
Body:
{
"site" : "site_remote_42",
"hash" : "<optional cached hash>"
}
If hash is set and matches the current site definition, the endpoint returns 304 Not Modified with no body. Otherwise it streams the new payload back. This makes it cheap to poll for changes.
GET /loggers/liveSubscribe to live value updates. The endpoint holds the connection open and writes one NDJSON line per new value received from the field bus.
Body:
| Field | Description |
|---|---|
address |
One or more address keys to watch (string or array) |
id |
Optional. Watcher id — pass the same id again to resume an existing subscription instead of creating a new one |
Response stream:
{"id":"4/7/25","value":21.5,"value_string":"21.5°C","value_date":"2026-04-08T13:42:01.000Z"}
{"id":"4/7/26","value":21.7,"value_string":"21.7°C","value_date":"2026-04-08T13:42:01.000Z"}
{"status":"alive"}
{"id":"4/7/25","value":21.6,"value_string":"21.6°C","value_date":"2026-04-08T13:42:11.000Z"}
A {"status":"alive"} keepalive line is emitted every second when there is no traffic, so clients can detect a dead connection.
The watcher persists across reconnects: if the client disconnects and reconnects within ~1 minute with the same id, it resumes where it left off. After 1 minute of inactivity, the watcher is destroyed.
Example — Node.js consumer:
var https = require('https')
var req = https.request({
method : 'POST',
host : 'gateway.example.com',
path : '/loggers/live',
headers : { 'Cookie' : 'weble.sid=...', 'Content-Type' : 'application/json' }
}, function(res){
var buf = ''
res.on('data', function(chunk){
buf += chunk
var lines = buf.split('\r\n')
buf = lines.pop()
lines.forEach(function(line){
if(!line) return
var update = JSON.parse(line)
if(update.status) return // keepalive
console.log(update.id, '=', update.value)
})
})
})
req.write(JSON.stringify({ address : ['4/7/25', '4/7/26'] }))
req.end()
POST /loggers/functionExecute a server-side function on a site. This is the only REST endpoint that lets you write back to the gateway through the loggers layer — typically used by the cloud to push value writes or address metadata updates to a remote box.
Body:
| Field | Description |
|---|---|
site |
Site id to target |
name |
Function name (whitelisted, see below) |
value |
Function-specific payload |
Whitelisted functions:
name |
Description | value shape |
|---|---|---|
write |
Write a decoded value to an address. Equivalent to gateways.writeValue |
{ "address" : "4/7/25", "value" : 1 } |
updateaddresslog |
Update address logging metadata in bulk. Used by the cloud after editing log settings remotely | [{ "id" : 23055, "log" : { ... } }, ...] |
Any other name is rejected with 400.
Example — write a value:
curl -b cookies.txt -X POST 'https://gateway.example.com/loggers/function' \
-H 'Content-Type: application/json' \
-d '{
"site" : "ab_cd_ef_01_02_03",
"name" : "write",
"value" : { "address" : "4/7/25", "value" : 1 }
}'
NOW=$(date -u +%Y-%m-%dT%H:%M:%SZ)
WEEK_AGO=$(date -u -d '7 days ago' +%Y-%m-%dT%H:%M:%SZ)
curl -b cookies.txt 'https://gateway.example.com/loggers/data' \
-H 'Content-Type: application/json' \
-d "{
\"address\" : [\"%M1\", \"%M2\"],
\"start\" : \"$WEEK_AGO\",
\"end\" : \"$NOW\",
\"aggregate\" : \"1h\",
\"streaming\" : true
}"
curl -b cookies.txt -N 'https://gateway.example.com/loggers/live' \
-H 'Content-Type: application/json' \
-d '{"address":["tempLiving","tempBedroom"]}' \
| grep -v '"alive"' >> /var/log/weble-tail.log
HASH=$(cat .last_site_hash 2>/dev/null || echo '')
RESPONSE=$(curl -b cookies.txt -s -w '%{http_code}' \
'https://gateway.example.com/loggers/siteData' \
-H 'Content-Type: application/json' \
-d "{\"site\":\"local\",\"hash\":\"$HASH\"}")
CODE=${RESPONSE: -3}
if [ "$CODE" = "304" ]; then echo 'unchanged'; else echo 'updated'; fi