The REST API is an HTTP/JSON veneer over the gateway's internal modules. It exposes a curated subset of the peers API — historical queries, live updates, value writes, system control, binary streams — through endpoints that any HTTP client can call without loading the peers runtime.
The Weble Cloud is the main consumer of the REST API: it uses it to fetch historical data from remote gateways, push configuration changes, and query live values for dashboards.
POST /auth/restAuthenticate with a username and a password. Returns a sessionId that you can use to maintain state. The HTTP session cookie is also set automatically by the response — most HTTP clients will replay it on subsequent calls.
Request body (JSON):
{
"username" : "admin",
"password" : "<md5 hash of the password>"
}
The password must be hashed with MD5 before being sent — the gateway compares hashes, not plaintext.
Response:
{
"sessionId" : "abcd1234-..."
}
After this call, your HTTP client carries a session cookie that authenticates every subsequent request.
Example with curl:
curl -c cookies.txt -X POST https://gateway.example.com/auth/rest \
-H 'Content-Type: application/json' \
-d '{"username":"admin","password":"5f4dcc3b5aa765d61d8327deb882cf99"}'
Then use -b cookies.txt on every subsequent call.
POST /authThe peers API entry point — POST /auth — returns the same sessionId plus the JavaScript bootstrap for the peers client (the source code of peers.js and socket.io-client.js). REST clients do not need that extra payload, so /auth/rest returns only the session id and is significantly smaller and faster.
If you only ever use REST endpoints, always prefer /auth/rest.
curl -b cookies.txt -X POST https://gateway.example.com/logout
Every endpoint described below requires the session cookie set by POST /auth/rest. Calls without a valid session return 403 Forbidden.
Most endpoints return JSON. Some endpoints support a ?format= query parameter:
| Value | Description |
|---|---|
json |
Standard JSON output |
json-no-eval |
JSON output with no eval-friendly types — safer when the consumer is a strict JSON parser |
When omitted, the default format is JSON.
Some endpoints return NDJSON (newline-delimited JSON) for large or live result sets — typically \r\n between records. For these, set the streaming=1 query parameter or pass streaming: true in the request body. Each line is a complete JSON object that can be parsed independently.
Endpoints that always stream (without the flag):
GET /loggers/data (when streaming is set)GET /loggers/live (always streams)Error responses use a standard JSON envelope:
{
"err" : "missing address"
}
or, for structured errors:
{
"error" : "site connector not found: ..."
}
HTTP status codes follow the usual convention: 200 on success, 400 on client errors, 401/403 on auth failures, 500 on server errors.
| Section | Path prefix | Description |
|---|---|---|
| Loggers | /loggers/* |
Historical timeseries queries, live value subscriptions, site listing, value writes |
| Peers dispatcher | /peers/{module}/{method} |
Generic dispatcher: invoke any peers method via HTTP |
| Streaming | /peers/{driver}/{id}/streaming |
Binary upload / download for files transferred through field-bus drivers |
| Logs | /peers/{driver}/{id}/logs_* |
Retrieve driver diagnostic logs in file / raw / JSON formats |
| System | /system/* |
Firmware upgrade, backup, snapshot, restore, reboot |
The REST API only covers the most common operations. If you need:
newValue, gatewayState, etc) without polling/peers/*…use the peers API instead. It runs over WebSocket and gives you the full surface of every module in a single bidirectional connection.