Skip to content

First request

Document Context

  • Purpose: Provides quick-start guide with minimal curl commands to verify whatwatt Go device connectivity and demonstrate basic data retrieval
  • When to use: First-time device setup, connectivity testing, API proof-of-concept, new developer onboarding
  • Prerequisites: Device on local network, curl installed, basic command line knowledge
  • Related to: Device discovery, authentication setup, REST API polling, system information
  • Validates against: Live device responses via /api/v1/system and, on licensed devices, /api/v1/report

Key Facts

  • Quick test endpoints: /api/v1/system for every device, /api/v1/report only with Plus or higher
  • Methods: GET requests only
  • Authentication: Optional (required only if device protection enabled)
  • Response format: JSON with device metadata and energy measurements
  • Network discovery: Use mDNS hostname whatwatt-XXXXXX.local or IP address
  • No meter required: System endpoint works without meter connection
  • Meter required: Report endpoint needs connected energy meter for meaningful data
  • License requirement: /api/v1/report requires Plus or higher
  • Next steps: Choose REST polling vs. MQTT streaming based on use case

This page shows two minimal requests to verify connectivity and see live data, then points you to full guides.

Authentication

When a Web UI password is set, HTTP endpoints require HTTP authentication.

Firmware 1.10.X and later: Uses HTTP Digest authentication - Server challenges with WWW-Authenticate: Digest … (realm is the device hostname) - Algorithm: MD5-sess (device advertises MD5-sess; integrity variant supported) - qop: auth (and optionally auth-int for requests with body integrity) - Nonce and opaque are issued by the device; the client must include cnonce and increment nc - Expired nonce: server may return 401 with WWW-Authenticate: …, stale=true. In that case, retry the same request once using the new server challenge, a new cnonce, and reset nc=00000001.

Firmware before 1.10.X: Uses HTTP Basic authentication - Server challenges with WWW-Authenticate: Basic realm="..." - Credentials are base64-encoded in Authorization: Basic <encoded-credentials>

Recommended approach: Use --anyauth in curl to automatically detect and use the appropriate method:

curl --anyauth -u ":<password>" http://whatwatt-ABCDEF.local/api/v1/system

1) System information (device)

# Replace host with your device hostname or IP
curl http://whatwatt-XXXXXX.local/api/v1/system
  • Fast health check and basic metadata
  • For details: see System Info

2) Current report (meter)

Requires Plus license

This endpoint group is available only with an active Plus or higher license. On devices without the required license, the firmware returns 404 License required for gated routes using the original HTTP method of the endpoint. See the REST API License Requirements page for the full endpoint list.

# Returns the latest parsed report from the meter
curl http://whatwatt-XXXXXX.local/api/v1/report
  • You’ll see power, energy, and meter fields when a meter is connected
  • Use this request only after confirming the device license is Plus or higher
  • For polling details: see REST → Polling
  • For live streaming: see REST → Streaming

Next steps