The Data Retrieval API gives approved integrations a consistent way to discover an organization's structure and read normalized time-series values. Start at the organization, follow the hierarchy to a metric, then request the data points recorded for that metric.
These APIs are for reporting, analytics, data exports, and integrations that need to read Waterly data outside the Waterly application. Each API token is assigned to an organization. Requests verify the token's scopes and organization access.
Discover accessible organizations with GET /api/organizations/v1, then use a
selected organization's data-model endpoint to walk its hierarchy or filter by a resource
kind or parent.
Query one metric or several resources over a date range. Values are returned with their value type, source, timestamps, and status flags.
https://connect.waterly.com. API routes
begin with /api. Store the host in configuration so the same integration can use
a different Waterly environment when needed.
An organization is the security boundary. System groups organize systems and can contain other system groups. A system contains sites; each site contains processes. A process can contain metrics directly or organize them under components. Data points are the timestamped values recorded for a metric.
| Resource | What it represents | Typical parent |
|---|---|---|
| Organization | A utility, company, or operating entity and the boundary for API access. | — |
| System group | A folder-like grouping used to organize systems. Groups may be nested. | Organization or system group |
| System | A water, wastewater, or related operating system with shared settings and time zone. | System group |
| Site | A physical or logical operating location within a system. | System |
| Process | A stage of treatment or operations at a site. | Site |
| Component | A piece of equipment or logical grouping within a process. | Process |
| Metric | A named measurement definition, such as flow, pressure, or chlorine residual. | Process or component |
| Data point | One value for a metric at a particular applied and measured time. | Metric |
Waterly issues a username and one-time visible secret for an API token. HTTP Digest uses a
challenge-response exchange so the secret itself is not placed in the request. The server
first returns 401 with a challenge; your HTTP client calculates a SHA-256 digest
for the request and tries again. Tools such as curl handle both steps automatically.
export WATERLY_API_USERNAME="your-api-username"
export WATERLY_API_SECRET="your-api-secret"
curl --digest \
--user "$WATERLY_API_USERNAME:$WATERLY_API_SECRET" \
"https://connect.waterly.com/api/organizations/v2/current"
/current identifies the assigned organization and token grants. Discovery
requires organization:read. To read an organization's systems, metrics, or data
points, use its ID as shown in the organization guide.
Resource list routes retain their assigned-organization behavior.
Collection endpoints return 50 records by default and accept limit values from 1
to 200. Do not construct or edit cursor values. When meta.has_next is true, make
the next Digest-authenticated request to the absolute URL in links.next.
{
"data": [ ... ],
"links": {
"self": "https://connect.waterly.com/api/sites/v2?limit=50",
"next": "https://connect.waterly.com/api/sites/v2?limit=50&cursor=eyJ...",
"prev": null
},
"meta": { "limit": 50, "has_next": true, "has_prev": false }
}/api/organizations/v1
Discover accessible organizations, confirm token identity, and select a data model.
System groups/api/system-groups/v1
Navigate top-level and nested organization groups.
Systems/api/systems/v1
Find systems and inspect their settings.
Sites/api/sites/v2
List operational locations within systems.
Processes/api/processes/v1
Discover operational stages within sites.
Components/api/components/v1
Find equipment and logical process groupings.
Metrics/api/metrics/v1
Discover measurement definitions and units.
Data points/api/data-points/v1
Read normalized time-series values.