PT EN

Qualidade da água

URL base: $BUSINESS_API

O objecto

idstring · obrigatório
parameterstring · obrigatório

um de residual_chlorine, ph, turbidity, e_coli, coliforms

unitstring · obrigatório
min_valuenumber · opcional
max_valuenumber · opcional
sourcestring · opcional
O objecto
{
  "id": "qua_2Jzoc3BWKBJMyVnCqz7SgxJgg3N",
  "parameter": "residual_chlorine",
  "unit": "unit",
  "min_value": 13.42,
  "max_value": 13.42,
  "source": "source"
}

Listar limites de qualidade

Registos

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.

Devolve

200 Success

Mostrar atributos
dataarray of QualityStandard · opcional
Mostrar atributos filhos
idstring · obrigatório
parameterstring · obrigatório

um de residual_chlorine, ph, turbidity, e_coli, coliforms

unitstring · obrigatório
min_valuenumber · opcional
max_valuenumber · opcional
sourcestring · opcional

Erros 400 · 403

Permissões business:monitoring:read · Funções: admin, analyst, field_supervisor, operations, owner, viewer

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

Definir um limite de qualidade

Registos

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.

Parâmetros

parameterstring · caminho · obrigatório

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

Corpo application/json

unitstring · obrigatório
min_valuenumber · opcional
max_valuenumber · opcional
sourcestring · opcional

Devolve

200 OK

Mostrar atributos
idstring · obrigatório
parameterstring · obrigatório

um de residual_chlorine, ph, turbidity, e_coli, coliforms

unitstring · obrigatório
min_valuenumber · opcional
max_valuenumber · opcional
sourcestring · opcional

Erros 400 · 403

Permissões business:monitoring:write · Funções: 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"
}'
Resposta 200
{
  "id": "qua_2Jzoc3BWKBJMyVnCqz7SgxJgg3N",
  "parameter": "residual_chlorine",
  "unit": "unit",
  "min_value": 13.42,
  "max_value": 13.42,
  "source": "source"
}

Listar amostras

Registos

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.

Parâmetros

location_typestring · consulta · opcional

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

asset_idstring · consulta · opcional

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

dma_idstring · consulta · opcional

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

statusstring · consulta · opcional

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

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

Devolve

200 OK

Mostrar atributos
dataarray of WaterSample · opcional
Mostrar atributos filhos
idstring · opcional
codestring · opcional
location_typestring · opcional

um de reservoir, zone

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

um de collected, analyzed

notesstring · opcional
has_moreboolean · opcional
next_cursorstring · opcional

Erros 400 · 403

Permissões business:monitoring:read · Funções: admin, analyst, field_supervisor, operations, owner, viewer

curl -X GET "$BUSINESS_API/water-quality/samples" \
  -H "Authorization: Bearer sk_test_..."
Resposta 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"
}

Registar uma amostra

Registos

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.

Corpo application/json

codestring · obrigatório
location_typestring · obrigatório

um de reservoir, zone

asset_idstring · opcional
dma_idstring · opcional
sampled_atstring (date-time) · obrigatório
collected_bystring · opcional
laboratorystring · opcional
notesstring · opcional

Devolve

201 OK

Mostrar atributos
idstring · opcional
codestring · opcional
location_typestring · opcional

um de reservoir, zone

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

um de collected, analyzed

notesstring · opcional

Erros 400 · 403

Permissões business:monitoring:write · Funções: 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."
}'
Resposta 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."
}

Obter uma amostra

Registos

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.

Parâmetros

idstring · caminho · obrigatório

ID of the water quality sample (smp_ prefix).

Devolve

200 OK

Mostrar atributos
idstring · opcional
codestring · opcional
location_typestring · opcional

um de reservoir, zone

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

um de collected, analyzed

notesstring · opcional

Erros 400 · 403

Permissões business:monitoring:read · Funções: admin, analyst, field_supervisor, operations, owner, viewer

curl -X GET "$BUSINESS_API/water-quality/samples/{id}" \
  -H "Authorization: Bearer sk_test_..."
Resposta 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."
}

Registar um resultado de análise

Registos

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.

Parâmetros

idstring · caminho · obrigatório

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

Corpo application/json

parameterstring · obrigatório
valuenumber · obrigatório
unitstring · obrigatório
methodstring · opcional
analyzed_atstring (date-time) · opcional

Devolve

201 OK

Mostrar atributos
idstring · opcional
sample_idstring · opcional
parameterstring · opcional
valuenumber · opcional
unitstring · opcional
methodstring · opcional
analyzed_atstring (date-time) · opcional
compliancestring · opcional

um de compliant, non_compliant, not_evaluated

min_appliednumber · opcional
max_appliednumber · opcional

Erros 400 · 403

Permissões business:monitoring:write · Funções: 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"
}'
Resposta 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
}

Listar resultados de análises

Registos

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.

Parâmetros

parameterstring · caminho · opcional

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

sample_idstring · consulta · opcional

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

compliancestring · consulta · opcional

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 · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

Devolve

200 OK

Mostrar atributos
dataarray of WaterResult · opcional
Mostrar atributos filhos
idstring · opcional
sample_idstring · opcional
parameterstring · opcional
valuenumber · opcional
unitstring · opcional
methodstring · opcional
analyzed_atstring (date-time) · opcional
compliancestring · opcional

um de compliant, non_compliant, not_evaluated

min_appliednumber · opcional
max_appliednumber · opcional
has_moreboolean · opcional
next_cursorstring · opcional

Erros 400 · 403

Permissões business:monitoring:read · Funções: admin, analyst, field_supervisor, operations, owner, viewer

curl -X GET "$BUSINESS_API/water-quality/results" \
  -H "Authorization: Bearer sk_test_..."
Resposta 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"
}