Organizations API

Confirm which organization your token represents, then discover the systems, sites, processes, components, and metrics available to it.

Start every integration here

An API token belongs to one organization. Call /current during setup to verify the organization ID, token username, and granted scopes. Use that organization ID in data-model and data-point requests.

Organization access — Supplying a different organization ID does not expand access. Waterly verifies the requested ID against the token's organization on every organization-scoped route.

Get the current organization

GET/api/organizations/v1/currentIdentify this token

Example request

curl --digest \
  --user "$WATERLY_API_USERNAME:$WATERLY_API_SECRET" \
  "https://connect.waterly.com/api/organizations/v1/current"

Example response

{
  "data": {
    "organization": {
      "id": 123,
      "name": "Clearwater Utilities",
      "fiscal_year_start_date": "1901-01-01"
    },
    "token": {
      "username": "clearwater-reporting",
      "scopes": ["organization:read", "data-model:read", "data-points:read"]
    }
  },
  "links": {
    "self": "https://connect.waterly.com/api/organizations/v1/current",
    "data_model": "https://connect.waterly.com/api/organizations/v1/123/data-model",
    "docs": "https://connect.waterly.com/docs",
    "openapi": "https://connect.waterly.com/openapi.json"
  }
}

Get the organization by ID

After discovering ID 123, the canonical ID route returns the same organization envelope.

GET/api/organizations/v1/{organizationId}

curl --digest \
  --user "$WATERLY_API_USERNAME:$WATERLY_API_SECRET" \
  "https://connect.waterly.com/api/organizations/v1/123"

Discover the organization data model

This cursor-paginated endpoint can return the complete flattened hierarchy or a filtered slice. Use kind for one resource type. To list children, supply both parent_kind and parent_id.

GET/api/organizations/v1/{organizationId}/data-model

Example: list sites in system 40

curl --digest \
  --user "$WATERLY_API_USERNAME:$WATERLY_API_SECRET" \
  "https://connect.waterly.com/api/organizations/v1/123/data-model?kind=site&parent_kind=system&parent_id=40"

Example response

{
  "organization": { "id": 123, "name": "Clearwater Utilities" },
  "data": [{
    "kind": "site",
    "id": 55,
    "name": "North Treatment Plant",
    "parent": { "kind": "system", "id": 40 },
    "order": 1,
    "attributes": { "site_type": "treatment_plant" }
  }],
  "links": { "self": "...", "next": null, "prev": null },
  "meta": { "limit": 50, "has_next": false, "has_prev": false }
}

Get one data-model item

Use a kind and ID from discovery to retrieve one item. The children link is present when the resource can contain other resources; metrics return null.

GET/api/organizations/v1/{organizationId}/data-model/{kind}/{id}

curl --digest \
  --user "$WATERLY_API_USERNAME:$WATERLY_API_SECRET" \
  "https://connect.waterly.com/api/organizations/v1/123/data-model/site/55"

{
  "data": {
    "kind": "site", "id": 55, "name": "North Treatment Plant",
    "parent": { "kind": "system", "id": 40 },
    "order": 1, "attributes": { "site_type": "treatment_plant" }
  },
  "links": {
    "self": "https://connect.waterly.com/api/organizations/v1/123/data-model/site/55",
    "children": "https://connect.waterly.com/api/organizations/v1/123/data-model?parent_id=55&parent_kind=site"
  }
}