API

ZiggyMeter exposes a simple, secure REST API for configuration, status, and integrations. This page summarizes how to connect and authenticate before using the endpoints.

See the Endpoints chapter for the complete list of endpoints.

Transport

• HTTPS only: all requests go over TLS on port 443.
• JSON by default: send Content-Type: application/json and expect JSON responses unless noted otherwise.

Authentication

Header format:

Authorization: Bearer <token>

Token lifetime:

• Tokens are time-limited. The login response returns the remaining validity in seconds via expires_in_secs.
• Refresh the token before it expires or handle 401 Unauthorized by logging in again.

Example login response:

{
    "token": "<token>",
    "expires_in_secs": 3600
}

Quick Start

1. Obtain a token

   curl -X POST \
   https://<host>/login \
   -H "Content-Type: application/json" \
   -d '{
       "username": "<username>",
       "password": "<password>"
   }'

2. Call any API with the token

   curl -X GET \
   https://<host>/api/v1/system/status \
   -H "Authorization: Bearer <token>" \
   -H "Accept: application/json"

   If the token is missing or invalid, the API will return an authentication error.

3. Logout

   curl -X POST \
   https://<host>/api/v1/system/logout \
   -H "Authorization: Bearer <token>"

Calling logout immediately invalidates the current token; further requests with this token will fail with authentication errors. To continue, obtain a new token by logging in again.

TIP

For test purposes you may consider to add -k option to curl that allows connections to self‑signed or otherwise untrusted certs.

Safer alternatives: Install a valid cert on the server, or point curl to a trusted CA with --cacert <ca.pem> (or use your system trust store).

Upgrade

When performing an upgrade, limit the data upload rate; otherwise the device will report an error. The example below shows throttling with curl's --limit-rate option.

curl -X POST  \
https://<host>/api/v1/system/ota \
-H "Authorization: Bearer <token>" \
--data-binary "@XXXX-YYYY-00320-20250324T195250-ZiggyMeter-1.2.320.ota" \
--limit-rate 1024