WaterlyConnect Data Submission API

Accepts time-series tag measurements from any field device, industrial controller, or software system. A single POST endpoint receives device identity, an array of named readings, and a Unix timestamp — then routes the data into Waterly's platform for dashboards, alerts, and compliance reporting.

Integration Guides OpenAPI YAML

Overview

WaterlyConnect is a lightweight REST API for pushing operational data from external systems into the Waterly platform. It's designed for water and wastewater utilities that operate field sensors, PLCs, SCADA gateways, or any networked device that produces numeric readings.

Each submission carries three required elements: a top-level Unix timestamp, a device block that identifies the submitting system, and an array of tag measurements. Tags are named numeric values — things like WetWellLevel, ClearwellPressure, or ChlorineResidual — captured at a point in time.

Base URL — All requests go to https://app.waterlyapp.com/connect/submit. Contact support@waterly.com to confirm the endpoint and obtain credentials for your environment.

Credentials & Setup

Before making your first request, you need three values from the Waterly support team. These are assigned per integration and are not self-service.

Client token — The value for the x-waterly-connect-token request header. Treat this like a password.
Device id — A stable identifier for the system submitting data. Goes inside the device block on every request.
Device type — A short label describing the integration type (e.g. "SCADA Gateway", "Python Adapter"). Also part of the device block.

Authentication Headers

Every request must include two custom headers. There is no OAuth flow or session management — authentication is header-based on each individual request.

x-waterly-request-type

Required string

Identifies the request type. Must be set to the literal value WaterlyConnect for all data submissions.

Example: "WaterlyConnect"

x-waterly-connect-token

Required string

Your Waterly-issued client authentication token. Assigned per integration by the Waterly support team.

Example: "abc-pdq-xyz"

Endpoint

POST /submit Submit new tag data to WaterlyConnect

Required Headers

x-waterly-request-type

Required

"WaterlyConnect"

x-waterly-connect-token

Required

Your Waterly-issued token

Request Body — application/json

Must be a WaterlyConnectSubmission object. The example below shows two tag readings from a lift station.

{
  "timestamp": 1629489199,
  "device": {
    "id": "lift-station-04",
    "type": "SCADA Gateway",
    "lan_ip": "192.168.10.45",
    "serial": "LS04-ABC-9912"
  },
  "tags": [
    {
      "name": "WetWellLevel",
      "value": "12.7",
      "last_change_timestamp": 1629489199,
      "unit": "FT"
    },
    {
      "name": "PumpRuntimeToday",
      "value": "3420",
      "last_change_timestamp": 1629489180,
      "unit": "SEC"
    }
  ]
}

Responses

200 OK — Data accepted and queued for processing.

400 Bad Request — Malformed JSON or a required field is missing. Check the payload against the schema.

500 Internal Server Error — A Waterly-side error occurred. If this persists, contact support.

Schemas

WaterlyConnectSubmission

Top-level request body. Every submission must include a timestamp, a device block, and at least one tag.

Field	Type	Required	Description
timestamp	integer	Yes	Unix timestamp (seconds since epoch) representing when this submission was generated.e.g. 1629489199
device	Device	Yes	Identifies the hardware or software system sending this data. The id and type are assigned by Waterly.
tags	array[TagDatum]	Yes	One or more named tag measurements. Each tag name must be unique per device id within a single submission.

Device

Describes the system sending the submission. The id and type values are assigned during onboarding by the Waterly team and must match exactly.

Field	Type	Required	Description
id	string	Yes	Stable identifier for this device or system, assigned by Waterly.e.g. "lift-station-04"
type	string	Yes	Short label for the integration type, assigned by Waterly.e.g. "SCADA Gateway"
lan_ip	string	Optional	Internal LAN IP address of the submitting hardware, if applicable.e.g. "192.168.10.45"
wan_ip	string	Optional	External/Internet-facing IP address of the hardware, if applicable.e.g. "203.0.113.42"
serial	string	Optional	Hardware serial number for physical devices.e.g. "LS04-ABC-9912"
uptime_millis	integer	Optional	Milliseconds since the device last rebooted. Useful for detecting unexpected restarts.e.g. 23452323234

TagDatum

A single named measurement. Tag names should be consistent across submissions for the same device — Waterly uses them as the identity for each data series.

Field	Type	Required	Description
name	string	Yes	Tag or metric name. Must be unique per device id within a submission. Keep names stable across submissions.e.g. "WTP1_FL_WEIGHT"
value	string	Yes	Numeric measurement value transmitted as a string. Decimal values are supported.e.g. "900.2"
last_change_timestamp	integer	Yes	Unix timestamp (seconds since epoch) for when this value was sampled or last changed.e.g. 1603806033
unit	string	Optional	Human-readable unit label for the measurement.e.g. "LBR", "FT", "GPM", "PSI"
type	integer	Optional	Unit type enum, as assigned by Waterly administrators. Typically unused.e.g. 0