Skip to main content
API docs by Redocly

Sonic local API (2025.2.0)

Overview

This is the API hosted on Sonic allowing to manage the device and retrieve collected data. Available endpoints allow to:

  • Get device state
  • Get/change valve state
  • Get/control buzzer
  • Get telemetry data
  • Get power supply status
  • Get/change networking status
  • Get auto shut-off settings
  • Get auto shut-off report
  • Execute a command (reboot)
  • Get/set webhook URL

Whenever unknown request is received, API returns a 404 Not Found response.

Webhook

If a webhook is configured, the device will send PUT requests for the following events: "auto-shut-off-report", "telemetry", "valve", "power-supply-changed", "wifi-changed" and "online".

telemetry

Message sent when new telemetry data was collected.

Label Unit
Flow ml/min
Pressure mbar
Temperature °C
Event volume ml
Event duration s 
{
    "type": "telemetry",
    "data":
        {
            "flow": integer,
            "pressure": integer,
            "temperature": integer,
            "event": { "volume": integer, "duration": integer },
            "errors": ["flow"/"pressure"/"temperature"],
        },
}

valve

Message sent when the valve state changes.

{
    "type": "valve",
    "data": {
        "state": "open"/"closed"/"opening"/"closing/unknown"
    }
}

power-supply-changed

Message sent when the power supply status changes.

{
    "type": "power-supply-changed",
    "data": {
        "supply": "battery"/"external"/"external+battery"
        ]
    }
}

auto-shut-off-report

Message sent when the auto shut-off module gets triggered due to detecting a potential leak.

Label Unit
Volume ml
Duration s
Timestamp ms 
{
    "type": "auto-shut-off-report",
    "data":
        {
            "type": ["VOLUME_THRESHOLD"/"DURATION_THRESHOLD"],
            "volume": integer,
            "duration": integer,
            "timestamp": integer,
        },
}

Sonic

Get device state

Retrieve specified information from the device: valve state, water flow indicator, MQTT and Wi-Fi connection status, power supply, firmware version, water meter data, and device uptime.

Label Unit
Water meter volume L
Water meter duration min
Uptime s

Responses

Response samples

Content type
{
  • "valveState": "closed",
  • "waterFlowing": false,
  • "mqttConnected": true,
  • "wifiConnected": true,
  • "powerSupply": "external",
  • "firmwareVersion": "2024.1.0",
  • "serialNumber": "abcdef1234567890",
  • "waterMeter": {
    },
  • "uptime": 1024560,
  • "buzzerPlaying": false
}

Get valve state

Retrieve the current state of the valve.

Responses

Response samples

Content type
application/vnd.wtg.local.valve.v1+json
{
  • "state": "open"
}

Set valve state

Request the change of the valve state. If the valve is already in the desired state, its position won't change.

Request Body schema: application/vnd.wtg.local.valve-change.v1+json
required
state
string
Default: "close"
Enum: "open" "close"

Responses

Request samples

Content type
application/vnd.wtg.local.valve-change.v1+json
{
  • "state": "open"
}

Get buzzer status

Retrieve the current status of the buzzer, including whether it's playing and the current sound.

Responses

Response samples

Content type
application/vnd.wtg.local.buzzer.v1+json
{
  • "playing": false,
  • "sound": "beep"
}

Control buzzer

Control the buzzer by playing a song or stopping playback. Available actions:

  • start: Start playing a specified song with optional interval and repeat count
  • stop: Stop the current playback

Supported songs: beep, christmas_1, christmas_2

Label Unit
Interval ms
Times count
Request Body schema:
required
action
required
string
Enum: "start" "stop"

Action to perform (start or stop buzzer).

name
string

Name of the sound to play (required when action is "start").

interval
integer
Default: 1000

Interval between sound repetitions in milliseconds (optional, default 1000).

times
integer
Default: 1

Number of times to repeat the sound (optional, default 1 = play once, X = play X times).

Responses

Request samples

Content type
{
  • "action": "start",
  • "name": "beep",
  • "interval": 1000,
  • "times": 3
}

Get supported buzzer sounds

Retrieve the list of supported sound names that can be played via the buzzer.

Responses

Response samples

Content type
application/vnd.wtg.local.buzzer-sounds.v1+json
{
  • "sounds": [
    ]
}

Get telemetry data

Retrieve sensors readings from the device. This includes: flow rate, pressure, water temperature, ongoing event data and potential errors. When an error is detected, the corresponding value is excluded from the payload. When water is not flowing, the event data is excluded from the payload.

Label Unit
Flow rate ml/min
Pressure mbar
Water temperature °C
Event volume ml
Event duration s

Responses

Response samples

Content type
application/vnd.wtg.local.telemetry.v1+json
{
  • "flow": 6800,
  • "pressure": 2320,
  • "temperature": 0,
  • "event": {
    },
  • "errors": [
    ]
}

Get power status

Retrieve the power status of the device. When the device is running only on external power supply, the battery voltage is excluded from the payload.

Label Unit
Battery voltage mV

Responses

Response samples

Content type
application/vnd.wtg.local.power.v1+json
{
  • "battery": false,
  • "external": true,
  • "batteriesVoltage": 6800
}

Get networking status

Retrieve the networking status of the device.

Label Unit
RSSI dBm
Wi-Fi uptime ms
MQTT uptime ms

Responses

Response samples

Content type
application/vnd.wtg.local.networking.v1+json
{
  • "mqttConnected": true,
  • "wifiConnected": true,
  • "ip": "192.168.21.37",
  • "gateway": "192.168.1.0",
  • "subnet": "192.168.1.0/24",
  • "ssid": "MyWi-Fi",
  • "rssi": -45,
  • "wifiUpTime": 1024560,
  • "mqttUpTime": 1023450
}

Update networking configuration

Update the networking configuration of the system.

Request Body schema: application/vnd.wtg.local.network-change.v1+json
required
ssid
string

SSID of the Wi-Fi network to connect.

password
string

Password of the Wi-Fi network to connect.

Responses

Request samples

Content type
application/vnd.wtg.local.network-change.v1+json
{
  • "ssid": "MyWi-Fi",
  • "password": "password"
}

Get auto shut-off settings

Retrieve the auto shut-off settings of the device.

Label Unit
Volume threshold L
Duration threshold min

Responses

Response samples

Content type
application/vnd.wtg.local.auto-shut-off.v1+json
{
  • "enabled": true,
  • "volumeThreshold": 300,
  • "durationThreshold": 60
}

Get auto shut-off report

Retrieve the auto shut-off report of the system.

Label Unit
Volume ml
Duration s
Timestamp ms

Responses

Response samples

Content type
application/vnd.wtg.local.auto-shut-off.report.v1+json
{
  • "type": "VOLUME_THRESHOLD",
  • "volume": 300,
  • "duration": 60000,
  • "timestamp": 1623456789
}

Execute a command

Execute a specific command on the device.

Command Description
reboot Software reboot of the device
Request Body schema: application/vnd.wtg.local.command.v1+json
required
type
string
Value: "reboot"

Type of the command to execute.

Responses

Request samples

Content type
application/vnd.wtg.local.command.v1+json
{
  • "type": "reboot"
}

Get webhook URL

Retrieve the webhook URL of the system.

Responses

Response samples

Content type
application/vnd.wtg.local.webhook.v1+json
{}

Update webhook URL

Update the webhook URL of the system.

Request Body schema: application/vnd.wtg.local.webhook.v1+json
required
url
string

URL of the webhook.

Responses

Request samples

Content type
application/vnd.wtg.local.webhook.v1+json
{}

Delete webhook URL

Clear the webhook URL of the system.

Responses