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" : "your-password"
}
Send the password as it is, over HTTPS. Do not hash it: the gateway checks it against the salted hash stored for the account, and an MD5 hash is refused.
Response:
{
"sessionId" : "abcd1234-..."
}
After this call, your HTTP client carries a session cookie that authenticates every subsequent request. On a wrong username or password the response is 500 with { "err" : "UNKNOWN_ACCOUNT" }.
Example with curl:
curl -c cookies.txt -X POST https://gateway.example.com/auth/rest \
-H 'Content-Type: application/json' \
-d '{"username":"admin","password":"your-password"}'
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 https://gateway.example.com/logout
After 5 failed logins in a row, the gateway refuses every login for 5 seconds, then twice as long after each new failure, up to 5 minutes. A successful login resets the counter. During the wait, login calls answer 500 with:
{ "err" : "TOO_MANY_TENTATIVE", "data" : <time of the next allowed attempt, in milliseconds since 1970> }
Instead of a session cookie, each request can carry its own credentials:
X-API-Key: wbx_... The key is generated in Administration › Access, on the row of the account, and is shown only once.curl -u 'admin:your-password' ...The request runs with the rights of that account.
Every endpoint described below requires an authenticated session: the cookie set by POST /auth/rest, an API key, or Basic authentication (see 1.5). Without one, /peers/* answers 401, /loggers/* answers 403, and /system/* redirects to the login page. When the role of the account does not allow the call, the answer is 403.
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 when a call has no session or no right, 500 on server errors. A failed login itself answers 500.
| 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/gateways/{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.