Understand your operation. Read the data behind it.

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.

Make your first request Learn Digest authentication OpenAPI Docs

What the Data Retrieval API provides

These APIs are for reporting, analytics, data exports, and integrations that need to read Waterly data outside the Waterly application. Every response is scoped to the organization assigned to your API token.

Discover the data model

List Waterly resources one type at a time, filter by a parent, or use the organization data-model endpoint to walk the complete hierarchy.

Read normalized values

Query one metric or several resources over a date range. Values are returned with their value type, source, timestamps, and status flags.

Base URL — Examples use 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.

How Waterly resources fit together

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.

Organization Access boundary

System group Can nest groups

System Utility or facility system

Site Operational location

Process Treatment or workflow stage

Metric May belong to a process

Component → Metric Or group metrics by equipment

Data points Timestamped metric values

Resource descriptions

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

Authenticate every request with HTTP Digest

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/v1/current"

Authentication guide

Follow pagination links

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/v1?limit=50",
    "next": "https://connect.waterly.com/api/sites/v1?limit=50&cursor=eyJ...",
    "prev": null
  },
  "meta": { "limit": 50, "has_next": true, "has_prev": false }
}

Choose an API guide

Organizations/api/organizations/v1

Confirm identity and explore the complete 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/v1

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.