Topology: Nodes

Base URL: $BUSINESS_API

List network graph nodes

Logs

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.

Parameters

limitinteger · query · optional

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

afterstring · query · optional

Opaque cursor returned by the previous page.

node_typestring · query · optional

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

one of source_river, source_borehole, treatment_plant, reservoir, dma_inlet, junction, customer_tap

service_area_idstring · query · optional

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

dma_idstring · query · optional

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

qstring · query · optional

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

Returns

200 Nodes

Show attributes
dataarray of TopologyNode · optional
Show child attributes
idstring · required
tenant_idstring · required
node_codestring · required
namestring · required
node_typestring · required

one of source_river, source_borehole, treatment_plant, reservoir, dma_inlet, junction, customer_tap

elevation_metersnumber · required
storage_capacity_m3integer (int64) · required
latitudenumber · required
longitudenumber · required
activeboolean · required
service_area_idstring · optional
dma_idstring · optional
device_idstring · optional

Level or flow device reporting measurements

meter_idstring · optional

Customer meter attributed to a customer_tap

meter_serialstring · optional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · optional

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

created_atstring (date-time) · required
updated_atstring (date-time) · required
has_moreboolean · optional
next_cursorstring · optional

Permissions network:read · Roles: admin, analyst, field_reader, field_supervisor, operations, owner, viewer

curl -X GET "$BUSINESS_API/topology/nodes" \
  -H "Authorization: Bearer sk_test_..."
Response 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"
}

Create topology node

Logs

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.

Body application/json

asset_idstring · optional

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

node_codestring · optional

Required unless asset_id is set

namestring · optional
node_typestring · required

one of source_river, source_borehole, treatment_plant, reservoir, dma_inlet, junction, customer_tap

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

Required for dma_inlet

device_idstring · optional
meter_idstring · optional

Returns

201 Node

Show attributes
idstring · required
tenant_idstring · required
node_codestring · required
namestring · required
node_typestring · required

one of source_river, source_borehole, treatment_plant, reservoir, dma_inlet, junction, customer_tap

elevation_metersnumber · required
storage_capacity_m3integer (int64) · required
latitudenumber · required
longitudenumber · required
activeboolean · required
service_area_idstring · optional
dma_idstring · optional
device_idstring · optional

Level or flow device reporting measurements

meter_idstring · optional

Customer meter attributed to a customer_tap

meter_serialstring · optional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · optional

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

created_atstring (date-time) · required
updated_atstring (date-time) · required

Permissions network:write · Roles: 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"
}'
Response 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"
}

Get a graph node

Logs

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.

Parameters

idstring · path · required

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

Returns

200 Node

Show attributes
idstring · required
tenant_idstring · required
node_codestring · required
namestring · required
node_typestring · required

one of source_river, source_borehole, treatment_plant, reservoir, dma_inlet, junction, customer_tap

elevation_metersnumber · required
storage_capacity_m3integer (int64) · required
latitudenumber · required
longitudenumber · required
activeboolean · required
service_area_idstring · optional
dma_idstring · optional
device_idstring · optional

Level or flow device reporting measurements

meter_idstring · optional

Customer meter attributed to a customer_tap

meter_serialstring · optional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · optional

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

created_atstring (date-time) · required
updated_atstring (date-time) · required

Permissions network:read · Roles: admin, analyst, field_reader, field_supervisor, operations, owner, viewer

curl -X GET "$BUSINESS_API/topology/nodes/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 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"
}

Update a graph node

Logs

PUT /topology/nodes/{id}

node_code and node_type are permanent.

Parameters

idstring · path · required

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

Body application/json

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

Returns

200 Updated node

Show attributes
idstring · required
tenant_idstring · required
node_codestring · required
namestring · required
node_typestring · required

one of source_river, source_borehole, treatment_plant, reservoir, dma_inlet, junction, customer_tap

elevation_metersnumber · required
storage_capacity_m3integer (int64) · required
latitudenumber · required
longitudenumber · required
activeboolean · required
service_area_idstring · optional
dma_idstring · optional
device_idstring · optional

Level or flow device reporting measurements

meter_idstring · optional

Customer meter attributed to a customer_tap

meter_serialstring · optional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · optional

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

created_atstring (date-time) · required
updated_atstring (date-time) · required

Permissions network:write · Roles: 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"
}'
Response 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"
}

Delete a node with no links and no ledger history

Logs

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.

Parameters

idstring · path · required

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

Returns

204 Deleted

Errors 409

Permissions network:write · Roles: admin, operations, owner

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

Deleted