Water quality

Base URL: $BUSINESS_API

The object

idstring · required
parameterstring · required

one of residual_chlorine, ph, turbidity, e_coli, coliforms

unitstring · required
min_valuenumber · optional
max_valuenumber · optional
sourcestring · optional
The object
{
  "id": "qua_2Jzoc3BWKBJMyVnCqz7SgxJgg3N",
  "parameter": "residual_chlorine",
  "unit": "unit",
  "min_value": 13.42,
  "max_value": 13.42,
  "source": "source"
}

List configured quality limits

Logs

GET /water-quality/standards

Returns the water quality limits the tenant has configured, one per parameter, in a data array ordered by parameter name. These limits decide the compliance verdict of new results, and parameters without a standard are reported as not_evaluated. Requires monitoring read access.

Returns

200 Success

Show attributes
dataarray of QualityStandard · optional
Show child attributes
idstring · required
parameterstring · required

one of residual_chlorine, ph, turbidity, e_coli, coliforms

unitstring · required
min_valuenumber · optional
max_valuenumber · optional
sourcestring · optional

Errors 400 · 403

Permissions business:monitoring:read · Roles: admin, analyst, field_supervisor, operations, owner, viewer

curl -X GET "$BUSINESS_API/water-quality/standards" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "qua_2Jzoc3BWKBJMyVnCqz7SgxJgg3N",
      "parameter": "residual_chlorine",
      "unit": "unit",
      "min_value": 13.42,
      "max_value": 13.42,
      "source": "source"
    }
  ]
}

Put quality standard

Logs

PUT /water-quality/standards/{parameter}

Set the limit for residual_chlorine, ph, turbidity, e_coli or coliforms

Creates or replaces the tenant's limit for one quality parameter and returns the stored standard. unit is required, at least one of min_value and max_value must be set, and min_value must not exceed max_value; source is free text naming where the limit comes from. Only results recorded afterwards use the new limits, since existing results keep the limits that applied at the time. Requires monitoring write access.

Parameters

parameterstring · path · required

Quality parameter the limit applies to: residual_chlorine, ph, turbidity, e_coli or coliforms; any other value is rejected with 400.

Body application/json

unitstring · required
min_valuenumber · optional
max_valuenumber · optional
sourcestring · optional

Returns

200 OK

Show attributes
idstring · required
parameterstring · required

one of residual_chlorine, ph, turbidity, e_coli, coliforms

unitstring · required
min_valuenumber · optional
max_valuenumber · optional
sourcestring · optional

Errors 400 · 403

Permissions business:monitoring:write · Roles: admin, operations, owner

curl -X PUT "$BUSINESS_API/water-quality/standards/{parameter}" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "unit": "unit",
  "min_value": 13.42,
  "max_value": 13.42,
  "source": "source"
}'
Response 200
{
  "id": "qua_2Jzoc3BWKBJMyVnCqz7SgxJgg3N",
  "parameter": "residual_chlorine",
  "unit": "unit",
  "min_value": 13.42,
  "max_value": 13.42,
  "source": "source"
}

List water samples

Logs

GET /water-quality/samples

Lists the tenant's water quality samples with cursor pagination (limit defaults to 20, maximum 100). Filters combine with AND and an unknown value returns an empty page. Requires monitoring read access.

Parameters

location_typestring · query · optional

Returns only samples taken at this kind of location: reservoir or zone.

asset_idstring · query · optional

Returns only samples taken at this network asset ID, as used for reservoir samples.

dma_idstring · query · optional

Returns only samples taken in this district metered area ID, as used for zone samples.

statusstring · query · optional

Returns only samples in this state: collected (no results yet) or analyzed (at least one result recorded).

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 OK

Show attributes
dataarray of WaterSample · optional
Show child attributes
idstring · optional
codestring · optional
location_typestring · optional

one of reservoir, zone

asset_idstring · optional
dma_idstring · optional
sampled_atstring (date-time) · optional
collected_bystring · optional
laboratorystring · optional
statusstring · optional

one of collected, analyzed

notesstring · optional
has_moreboolean · optional
next_cursorstring · optional

Errors 400 · 403

Permissions business:monitoring:read · Roles: admin, analyst, field_supervisor, operations, owner, viewer

curl -X GET "$BUSINESS_API/water-quality/samples" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "wat_2MihHYs5TeOt7Qe7TmYbpo8Drog",
      "code": "COD-2026-000142",
      "location_type": "reservoir",
      "asset_id": "ass_2IIXBYi79uuRV0QXd685rmSLhO0",
      "dma_id": "dma_2gE3tiwbLQQnDGcrVkstPO8Bjkg",
      "sampled_at": "2026-11-19T09:30:00Z",
      "collected_by": "collected by",
      "laboratory": "laboratory",
      "status": "collected",
      "notes": "Leitura confirmada no local."
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Record a sample at a reservoir or distribution zone

Logs

POST /water-quality/samples

Records a water sample collected in the field, with status collected, and returns 201. code and sampled_at are required; location_type must be reservoir (asset_id required) or zone (dma_id required). Results are added afterwards through the sample's results endpoint. Requires monitoring write access.

Body application/json

codestring · required
location_typestring · required

one of reservoir, zone

asset_idstring · optional
dma_idstring · optional
sampled_atstring (date-time) · required
collected_bystring · optional
laboratorystring · optional
notesstring · optional

Returns

201 OK

Show attributes
idstring · optional
codestring · optional
location_typestring · optional

one of reservoir, zone

asset_idstring · optional
dma_idstring · optional
sampled_atstring (date-time) · optional
collected_bystring · optional
laboratorystring · optional
statusstring · optional

one of collected, analyzed

notesstring · optional

Errors 400 · 403

Permissions business:monitoring:write · Roles: admin, operations, owner

curl -X POST "$BUSINESS_API/water-quality/samples" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "code": "COD-2026-000142",
  "location_type": "reservoir",
  "asset_id": "ass_2IIXBYi79uuRV0QXd685rmSLhO0",
  "dma_id": "dma_2gE3tiwbLQQnDGcrVkstPO8Bjkg",
  "sampled_at": "2026-11-19T09:30:00Z",
  "collected_by": "collected by",
  "laboratory": "laboratory",
  "notes": "Leitura confirmada no local."
}'
Response 201
{
  "id": "wat_2MihHYs5TeOt7Qe7TmYbpo8Drog",
  "code": "COD-2026-000142",
  "location_type": "reservoir",
  "asset_id": "ass_2IIXBYi79uuRV0QXd685rmSLhO0",
  "dma_id": "dma_2gE3tiwbLQQnDGcrVkstPO8Bjkg",
  "sampled_at": "2026-11-19T09:30:00Z",
  "collected_by": "collected by",
  "laboratory": "laboratory",
  "status": "collected",
  "notes": "Leitura confirmada no local."
}

Get a sample

Logs

GET /water-quality/samples/{id}

Returns one water quality sample with its location, collection time, collector, laboratory, notes and status (collected or analyzed). Responds 404 when the sample is not in the caller's tenant. Requires monitoring read access.

Parameters

idstring · path · required

ID of the water quality sample (smp_ prefix).

Returns

200 OK

Show attributes
idstring · optional
codestring · optional
location_typestring · optional

one of reservoir, zone

asset_idstring · optional
dma_idstring · optional
sampled_atstring (date-time) · optional
collected_bystring · optional
laboratorystring · optional
statusstring · optional

one of collected, analyzed

notesstring · optional

Errors 400 · 403

Permissions business:monitoring:read · Roles: admin, analyst, field_supervisor, operations, owner, viewer

curl -X GET "$BUSINESS_API/water-quality/samples/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "wat_2MihHYs5TeOt7Qe7TmYbpo8Drog",
  "code": "COD-2026-000142",
  "location_type": "reservoir",
  "asset_id": "ass_2IIXBYi79uuRV0QXd685rmSLhO0",
  "dma_id": "dma_2gE3tiwbLQQnDGcrVkstPO8Bjkg",
  "sampled_at": "2026-11-19T09:30:00Z",
  "collected_by": "collected by",
  "laboratory": "laboratory",
  "status": "collected",
  "notes": "Leitura confirmada no local."
}

Record an analysed parameter

Logs

POST /water-quality/samples/{id}/results

Record an analysed parameter; grades it against the limit and evaluates quality alarm rules

Records one laboratory measurement for a sample and returns 201 with the result. The value is checked against the tenant's configured standard for the parameter, storing the applied limits and a compliant or non_compliant verdict (not_evaluated when no standard exists). The sample moves to analyzed, and active water quality alarm rules for the parameter are evaluated, which can open, update or auto-resolve alarms. parameter must be a known parameter, unit is required, value must be finite and analyzed_at defaults to now; responds 404 when the sample does not exist.

Parameters

idstring · path · required

ID of the sample the measurement belongs to (smp_ prefix).

Body application/json

parameterstring · required
valuenumber · required
unitstring · required
methodstring · optional
analyzed_atstring (date-time) · optional

Returns

201 OK

Show attributes
idstring · optional
sample_idstring · optional
parameterstring · optional
valuenumber · optional
unitstring · optional
methodstring · optional
analyzed_atstring (date-time) · optional
compliancestring · optional

one of compliant, non_compliant, not_evaluated

min_appliednumber · optional
max_appliednumber · optional

Errors 400 · 403

Permissions business:monitoring:write · Roles: admin, operations, owner

curl -X POST "$BUSINESS_API/water-quality/samples/{id}/results" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "parameter": "parameter",
  "value": 13.42,
  "unit": "unit",
  "method": "method",
  "analyzed_at": "2026-11-19T09:30:00Z"
}'
Response 201
{
  "id": "wat_2PfSOlTqsHV40rTmKJ5CcZduOHR",
  "sample_id": "sam_2U07jOAhTYQNV60Pd6W5x8IZHUU",
  "parameter": "parameter",
  "value": 13.42,
  "unit": "unit",
  "method": "method",
  "analyzed_at": "2026-11-19T09:30:00Z",
  "compliance": "compliant",
  "min_applied": 1,
  "max_applied": 1
}

List laboratory results

Logs

GET /water-quality/results

Lists laboratory results recorded across the tenant's water quality samples, with cursor pagination (limit defaults to 20, maximum 100). Each result carries the limits that applied when it was recorded and its compliance verdict. Filters combine with AND and require monitoring read access.

Parameters

parameterstring · path · optional

Returns only results for this quality parameter: residual_chlorine, ph, turbidity, e_coli or coliforms.

sample_idstring · query · optional

Returns only results for this sample ID (smp_ prefix).

compliancestring · query · optional

Returns only results with this verdict: compliant, non_compliant or not_evaluated (no standard was configured for the parameter when the result was recorded).

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 OK

Show attributes
dataarray of WaterResult · optional
Show child attributes
idstring · optional
sample_idstring · optional
parameterstring · optional
valuenumber · optional
unitstring · optional
methodstring · optional
analyzed_atstring (date-time) · optional
compliancestring · optional

one of compliant, non_compliant, not_evaluated

min_appliednumber · optional
max_appliednumber · optional
has_moreboolean · optional
next_cursorstring · optional

Errors 400 · 403

Permissions business:monitoring:read · Roles: admin, analyst, field_supervisor, operations, owner, viewer

curl -X GET "$BUSINESS_API/water-quality/results" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "wat_2PfSOlTqsHV40rTmKJ5CcZduOHR",
      "sample_id": "sam_2U07jOAhTYQNV60Pd6W5x8IZHUU",
      "parameter": "parameter",
      "value": 13.42,
      "unit": "unit",
      "method": "method",
      "analyzed_at": "2026-11-19T09:30:00Z",
      "compliance": "compliant",
      "min_applied": 1,
      "max_applied": 1
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}