PT EN

Topologia: Nós

URL base: $BUSINESS_API

Listar nós da rede

Registos

GET /topology/nodes

Lists the network assets that are topology nodes in the tenant, newest first, with cursor pagination (limit defaults to 20, maximum 100). Assets that are not part of the topology are left out. Filters combine with AND and requires network read access.

Parâmetros

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

node_typestring · consulta · opcional

Returns only nodes of this type: source_river, source_borehole, treatment_plant, reservoir, dma_inlet, junction or customer_tap.

um de source_river, source_borehole, treatment_plant, reservoir, dma_inlet, junction, customer_tap

service_area_idstring · consulta · opcional

Returns only nodes assigned to this service area ID; an exact match.

dma_idstring · consulta · opcional

Returns only nodes that belong to this district metered area ID; an exact match.

qstring · consulta · opcional

Free-text search matched as a substring against the node's name or code.

Devolve

200 Nodes

Mostrar atributos
dataarray of TopologyNode · opcional
Mostrar atributos filhos
idstring · obrigatório
tenant_idstring · obrigatório
node_codestring · obrigatório
namestring · obrigatório
node_typestring · obrigatório

um de source_river, source_borehole, treatment_plant, reservoir, dma_inlet, junction, customer_tap

elevation_metersnumber · obrigatório
storage_capacity_m3integer (int64) · obrigatório
latitudenumber · obrigatório
longitudenumber · obrigatório
activeboolean · obrigatório
service_area_idstring · opcional
dma_idstring · opcional
device_idstring · opcional

Level or flow device reporting measurements

meter_idstring · opcional

Customer meter attributed to a customer_tap

meter_serialstring · opcional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · opcional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório
has_moreboolean · opcional
next_cursorstring · opcional

Permissões network:read · Funções: admin, analyst, field_reader, field_supervisor, operations, owner, viewer

curl -X GET "$BUSINESS_API/topology/nodes" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "data": [
    {
      "id": "top_20EbJqgt7ECLvqS5fuUZFei3bys",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "node_code": "NOD-2026-000142",
      "name": "Ana Matsinhe",
      "node_type": "source_river",
      "elevation_meters": 1,
      "storage_capacity_m3": 1,
      "latitude": -25.9653,
      "longitude": 32.5892,
      "active": true,
      "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
      "dma_id": "dma_2gE3tiwbLQQnDGcrVkstPO8Bjkg",
      "device_id": "dev_2E2J9iiRr2o7PWMrj8wJrQyb9sK",
      "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
      "meter_serial": "meter serial",
      "meter_holder_name": "Ana Matsinhe",
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Criar um nó da rede

Registos

POST /topology/nodes

Create a graph node, or give an existing asset a graph role with asset_id

Creates a topology node, either as a new network asset (node_code required, name defaults to the code) or by promoting an existing asset given in asset_id, whose asset type must match the node type. A dma_inlet node needs a dma_id, and each DMA may have only one inlet, so a second one is refused with 409, as is promoting an asset that is already a node. The node starts operational unless active is false, and storage_capacity_m3 must not be negative. Requires network write access and returns 201.

Corpo application/json

asset_idstring · opcional

Existing asset to give a graph role; node_code is then ignored

node_codestring · opcional

Required unless asset_id is set

namestring · opcional
node_typestring · obrigatório

um de source_river, source_borehole, treatment_plant, reservoir, dma_inlet, junction, customer_tap

elevation_metersnumber · opcional
storage_capacity_m3integer (int64) · opcional
latitudenumber · opcional
longitudenumber · opcional
activeboolean · opcional
service_area_idstring · opcional
dma_idstring · opcional

Required for dma_inlet

device_idstring · opcional
meter_idstring · opcional

Devolve

201 Node

Mostrar atributos
idstring · obrigatório
tenant_idstring · obrigatório
node_codestring · obrigatório
namestring · obrigatório
node_typestring · obrigatório

um de source_river, source_borehole, treatment_plant, reservoir, dma_inlet, junction, customer_tap

elevation_metersnumber · obrigatório
storage_capacity_m3integer (int64) · obrigatório
latitudenumber · obrigatório
longitudenumber · obrigatório
activeboolean · obrigatório
service_area_idstring · opcional
dma_idstring · opcional
device_idstring · opcional

Level or flow device reporting measurements

meter_idstring · opcional

Customer meter attributed to a customer_tap

meter_serialstring · opcional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · opcional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório

Permissões network:write · Funções: admin, operations, owner

curl -X POST "$BUSINESS_API/topology/nodes" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "asset_id": "ass_2IIXBYi79uuRV0QXd685rmSLhO0",
  "node_code": "NOD-2026-000142",
  "name": "Ana Matsinhe",
  "node_type": "source_river",
  "elevation_meters": 1,
  "storage_capacity_m3": 1,
  "latitude": -25.9653,
  "longitude": 32.5892,
  "active": true,
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "dma_id": "dma_2gE3tiwbLQQnDGcrVkstPO8Bjkg",
  "device_id": "dev_2E2J9iiRr2o7PWMrj8wJrQyb9sK",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN"
}'
Resposta 201
{
  "id": "top_20EbJqgt7ECLvqS5fuUZFei3bys",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "node_code": "NOD-2026-000142",
  "name": "Ana Matsinhe",
  "node_type": "source_river",
  "elevation_meters": 1,
  "storage_capacity_m3": 1,
  "latitude": -25.9653,
  "longitude": 32.5892,
  "active": true,
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "dma_id": "dma_2gE3tiwbLQQnDGcrVkstPO8Bjkg",
  "device_id": "dev_2E2J9iiRr2o7PWMrj8wJrQyb9sK",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_serial": "meter serial",
  "meter_holder_name": "Ana Matsinhe",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Obter um nó da rede

Registos

GET /topology/nodes/{id}

Returns one topology node with its type, location, elevation, storage capacity, DMA, linked meter and device, and active flag. An asset that exists but is not a topology node responds 404, like a missing one. Requires network read access.

Parâmetros

idstring · caminho · obrigatório

ID of the topology node, which is the ID of its network asset (ast_ prefix).

Devolve

200 Node

Mostrar atributos
idstring · obrigatório
tenant_idstring · obrigatório
node_codestring · obrigatório
namestring · obrigatório
node_typestring · obrigatório

um de source_river, source_borehole, treatment_plant, reservoir, dma_inlet, junction, customer_tap

elevation_metersnumber · obrigatório
storage_capacity_m3integer (int64) · obrigatório
latitudenumber · obrigatório
longitudenumber · obrigatório
activeboolean · obrigatório
service_area_idstring · opcional
dma_idstring · opcional
device_idstring · opcional

Level or flow device reporting measurements

meter_idstring · opcional

Customer meter attributed to a customer_tap

meter_serialstring · opcional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · opcional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório

Permissões network:read · Funções: admin, analyst, field_reader, field_supervisor, operations, owner, viewer

curl -X GET "$BUSINESS_API/topology/nodes/{id}" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "id": "top_20EbJqgt7ECLvqS5fuUZFei3bys",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "node_code": "NOD-2026-000142",
  "name": "Ana Matsinhe",
  "node_type": "source_river",
  "elevation_meters": 1,
  "storage_capacity_m3": 1,
  "latitude": -25.9653,
  "longitude": 32.5892,
  "active": true,
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "dma_id": "dma_2gE3tiwbLQQnDGcrVkstPO8Bjkg",
  "device_id": "dev_2E2J9iiRr2o7PWMrj8wJrQyb9sK",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_serial": "meter serial",
  "meter_holder_name": "Ana Matsinhe",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Actualizar um nó da rede

Registos

PUT /topology/nodes/{id}

node_code and node_type are permanent.

Parâmetros

idstring · caminho · obrigatório

ID of the topology node to update, which is its network asset ID (ast_ prefix); the node type cannot be changed.

Corpo application/json

namestring · opcional
elevation_metersnumber · opcional
storage_capacity_m3integer (int64) · opcional
latitudenumber · opcional
longitudenumber · opcional
activeboolean · opcional
service_area_idstring · opcional
dma_idstring · opcional
device_idstring · opcional
meter_idstring · opcional

Devolve

200 Updated node

Mostrar atributos
idstring · obrigatório
tenant_idstring · obrigatório
node_codestring · obrigatório
namestring · obrigatório
node_typestring · obrigatório

um de source_river, source_borehole, treatment_plant, reservoir, dma_inlet, junction, customer_tap

elevation_metersnumber · obrigatório
storage_capacity_m3integer (int64) · obrigatório
latitudenumber · obrigatório
longitudenumber · obrigatório
activeboolean · obrigatório
service_area_idstring · opcional
dma_idstring · opcional
device_idstring · opcional

Level or flow device reporting measurements

meter_idstring · opcional

Customer meter attributed to a customer_tap

meter_serialstring · opcional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · opcional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório

Permissões network:write · Funções: admin, operations, owner

curl -X PUT "$BUSINESS_API/topology/nodes/{id}" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Ana Matsinhe",
  "elevation_meters": 1,
  "storage_capacity_m3": 1,
  "latitude": -25.9653,
  "longitude": 32.5892,
  "active": true,
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "dma_id": "dma_2gE3tiwbLQQnDGcrVkstPO8Bjkg",
  "device_id": "dev_2E2J9iiRr2o7PWMrj8wJrQyb9sK",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN"
}'
Resposta 200
{
  "id": "top_20EbJqgt7ECLvqS5fuUZFei3bys",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "node_code": "NOD-2026-000142",
  "name": "Ana Matsinhe",
  "node_type": "source_river",
  "elevation_meters": 1,
  "storage_capacity_m3": 1,
  "latitude": -25.9653,
  "longitude": 32.5892,
  "active": true,
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "dma_id": "dma_2gE3tiwbLQQnDGcrVkstPO8Bjkg",
  "device_id": "dev_2E2J9iiRr2o7PWMrj8wJrQyb9sK",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_serial": "meter serial",
  "meter_holder_name": "Ana Matsinhe",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Eliminar um nó da rede

Registos

DELETE /topology/nodes/{id}

Deletes a topology node and its underlying network asset, returning 204 with no body. The node must have no links in either direction and no mass balance ledger history; otherwise the request fails with 409, so remove its links first. Responds 404 when the ID is not a topology node in the tenant and requires network write access.

Parâmetros

idstring · caminho · obrigatório

ID of the topology node to delete, which is its network asset ID (ast_ prefix).

Devolve

204 Deleted

Erros 409

Permissões network:write · Funções: admin, operations, owner

curl -X DELETE "$BUSINESS_API/topology/nodes/{id}" \
  -H "Authorization: Bearer sk_test_..."
Resposta 204

Deleted