Sites and assets API

These routes manage the asset tree of Hermetry Twin: sites, buildings, floors, rooms, lines, machines and your own kinds, where each device is placed, and the relations between assets and devices. The concepts are in Asset hierarchy. Paths are under https://<your host>/tenant/<tenantId>.

Routes

Default roles: reading is a User permission; changing assets, placements and relations is an Admin permission. Every change is written to the audit log (the changed field names, never the values).

The asset

Read-only fields in answers: iotAssetId, path (the codes from the top, for example /IST/BLD-A/GF), depth, createdAt, updatedAt.

{
    "name": "Compressor room",
    "kind": "ROOM",
    "code": "CR1",
    "parentId": "e5f6…",
    "timezone": "Europe/Istanbul",
    "attributes": {
        "area_m2": 42
    }
}

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/iot/assets' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Compressor room","kind":"ROOM","code":"CR1","parentId":"e5f6…","timezone":"Europe/Istanbul","attributes":{"area_m2":42}}'

{
    "asset": {
        "iotAssetId": "77aa…",
        "parentId": "e5f6…",
        "path": "/IST/BLD-A/GF/CR1",
        "depth": 4,
        "code": "CR1",
        "name": "Compressor room",
        "kind": "ROOM",
        "timezone": "Europe/Istanbul",
        "attributes": {
            "area_m2": 42
        },
        "…": "…"
    }
}

{
    "message": "Another asset already uses this code.",
    "code": "CONFLICT",
    "details": {
        "reason": "code_taken"
    }
}

PATCH takes the same fields except parentId. A new code rewrites the paths of every asset below in the same step.

GET /api/iot/assets/{assetId} adds ancestors (root first, each with id, code, name, kind), effectiveTimezone (its own, else the nearest ancestor’s), childCount and deviceCount.

List and tree

GET /api/iot/assets with view:

Alarm figures are included only when the caller may read alarms.

Move

POST /api/iot/assets/{assetId}/move
{ "parentId": "c3d4…" }

null makes it a top-level asset. Everything below moves with it. Moving an asset under itself or one of its descendants is refused: “An asset cannot be moved under itself or one of its own descendants.” (400, cycle). A path may be at most 1,024 characters (too_deep).

Delete

An asset with child assets is refused: “This asset still has child assets: move or delete them first.” (409, has_children). If another module reports that it still uses the asset, the delete is refused with 409 naming that module. Deleting an asset ends its device placements and relations; the devices themselves stay.

Place devices

POST /api/iot/assets/{assetId}/devices
{ "deviceIds": ["6f1c…", "8b2d…"] }

Each device has at most one place: placing it here moves it from where it was. The answer { "changes": [...] } lists what moved. One device at a time:

PUT /api/iot/devices/{deviceId}/placement
{ "iotAssetId": "77aa…" }      // or null to remove the placement

Both GET and PUT of .../placement answer { "placement": { "iotAssetId": "77aa…", "path": [ { "iotAssetId": "…", "code": "IST", "name": "Istanbul plant", "kind": "SITE" }, … ] } }, root first. A device with no place has iotAssetId: null.

GET /api/iot/assets/{assetId}/devices lists devices placed on the asset and, by default, below it (recursive=false for the asset alone): search, online=true|false, sort=name|connection:asc|desc, page from 1, pageSize up to 200. The answer is { items, total, page, pageSize }.

Relations

A relation links two ends, each an ASSET or a DEVICE, with a type: CONTAINS, MANAGES, FEEDS, MONITORS or your own (letters, digits, _, up to 32, stored in capitals).

{
    "fromType": "DEVICE",
    "fromId": "8b2d…",
    "toType": "DEVICE",
    "toId": "6f1c…",
    "type": "FEEDS",
    "additionalInfo": {
        "line": "DN150"
    }
}

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/iot/relations' \
  -H 'Content-Type: application/json' \
  -d '{"fromType":"DEVICE","fromId":"8b2d…","toType":"DEVICE","toId":"6f1c…","type":"FEEDS","additionalInfo":{"line":"DN150"}}'

{
    "relation": {
        "relationId": "…",
        "fromType": "DEVICE",
        "fromId": "8b2d…",
        "toType": "DEVICE",
        "toId": "6f1c…",
        "type": "FEEDS",
        "…": "…"
    }
}

{
    "message": "This relation already exists.",
    "code": "CONFLICT",
    "details": {
        "reason": "relation_exists"
    }
}

Rules:

• CONTAINS from an asset to a device is the device’s placement (use the placement routes). CONTAINS in any other shape is refused (placement_shape), and an asset inside another asset is set by moving it, not by a relation (parentage_is_move).
• A relation needs two different ends (self_relation).
• A missing end is 404 (end_not_found).

GET /api/iot/relations?entityType=ASSET&entityId={assetId} lists the relations of one end in both directions; or filter by fromType, fromId, toType, toId, type. limit 1 to 500 (default 200). The answer is { "relations": [...] }.

Search devices for a picker

GET /api/iot/devices/search?q=pump&limit=20&near=iot_asset:{assetId} answers { "devices": [{ "id", "name", "code", "hint" }] }: at most 20 devices by name, those of the given device or asset first, with hint naming where each is placed. It needs both iot_asset.assets.read and iot_device.devices.read.