Skip to main content

Trees

Hierarchical structures for organizing assets and navigating the platform.

What is a Tree?​

Trees are hierarchical structures in Beacon Tower that let you organize assets and dashboards into logical groupings. They're useful for reflecting physical locations (like site → building → floor → device), organizational structure, or any other hierarchy that makes sense for your use case.

Trees are optional—you don't need them for basic asset management. They become valuable when you want to:

  • Organize assets by location, department, or function
  • Aggregate analytics across groups of assets
  • Enable drill-down navigation in dashboards
  • Share organizational structures between organizations

An organization can have any number of trees, and trees can be shared between organizations.

Tree Structure​

Trees are built from nodes. The root node is the top-level entry point representing the entire tree.

Each node can contain:

  • Other nodes (child nodes)
  • Assets (linked, not moved)
  • Dashboards (linked, not moved)

Nodes and Edges​

Nodes are the building blocks of a tree. Each node has:

  • id — Unique identifier
  • displayName — Human-readable name
  • description — Optional description
  • type — Either NODE or ASSET

Nodes are connected by edges that define relationships:

fromType → toType (CONTAINS)

Valid edge types:

  • node → node (hierarchical structure)
  • node → asset (linking an asset to a node)
  • node → dashboard (linking a dashboard to a node)

Linking vs. Moving​

Assets and dashboards are linked to tree nodes, not moved or copied. This means:

  • An asset can appear in multiple trees or multiple nodes within a tree
  • A dashboard can be linked to several nodes
  • Unlinking removes only the connection—the asset or dashboard itself remains intact

Dashboard and Analytics Aggregation​

One of the most powerful features of trees is data aggregation. When you link a dashboard to a node in a tree, it can aggregate data from all assets at or below that node in the hierarchy.

For example, with a tree structure like this:

Site (root node)
├── Building A
│   ├── Floor 1
│   │   ├── HVAC Unit 1
│   │   └── HVAC Unit 2
│   └── Floor 2
│       └── HVAC Unit 3
└── Building B
    └── Floor 1
        └── HVAC Unit 4

A dashboard linked to "Building A" can automatically display aggregated metrics from HVAC Units 1, 2, and 3. A dashboard at "Site" would aggregate data from all units across both buildings.

This enables drill-down analytics: start with a site-level view, then drill into a specific building, floor, or device.

In the Beacon Tower UI, trees provide a hierarchical navigation experience:

  • Expand/collapse nodes to explore the hierarchy
  • Select a node to view its linked assets and dashboards
  • Navigate dashboards scoped to specific nodes
  • Search within trees to quickly find assets or nodes

Trees appear in the navigation panel and provide context-aware views of your assets and analytics.

Managing Trees​

Creating a Tree​

To create a tree, you create a root node using the Graph API:

curl -X POST "https://api.beacontower.ai/graph/nodes" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Corporate Campus",
    "description": "Main campus with buildings A, B, and C",
    "type": "NODE"
  }'

Response:

{
  "id": "node-12345",
  "displayName": "Corporate Campus",
  "description": "Main campus with buildings A, B, and C",
  "type": "NODE"
}

The returned id is your tree's root node ID.

Adding Child Nodes​

Create child nodes and link them with edges:

# Create a child node
curl -X POST "https://api.beacontower.ai/graph/nodes" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Building A",
    "description": "North building",
    "type": "NODE"
  }'

# Link the child to the parent (create edge)
curl -X POST "https://api.beacontower.ai/graph/edges" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fromId": "node-12345",
    "fromType": "node",
    "toId": "node-67890",
    "toType": "node",
    "relation": "CONTAINS"
  }'

Linking an Asset to a Node​

Link existing assets to tree nodes:

curl -X POST "https://api.beacontower.ai/graph/edges" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fromId": "node-67890",
    "fromType": "node",
    "toId": "asset-abc123",
    "toType": "asset",
    "relation": "CONTAINS"
  }'

Replace asset-abc123 with the ID of an existing asset. See Assets, Providers, and Bindings for details on creating assets.

Retrieving a Tree​

Get the full tree hierarchy:

# List all trees
curl -X GET "https://api.beacontower.ai/graph/trees" \
  -H "X-API-Key: YOUR_API_KEY"

# Get a specific tree starting from root node
curl -X GET "https://api.beacontower.ai/graph/trees/node-12345" \
  -H "X-API-Key: YOUR_API_KEY"

# Get tree hierarchy with depth control
curl -X GET "https://api.beacontower.ai/graph/trees/node-12345?depth=10" \
  -H "X-API-Key: YOUR_API_KEY"

Updating and Deleting Nodes​

Update a node:

curl -X PATCH "https://api.beacontower.ai/graph/nodes/node-67890" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Building A - Renovated",
    "description": "North building (renovated 2026)"
  }'

Delete a node:

curl -X DELETE "https://api.beacontower.ai/graph/nodes/node-67890" \
  -H "X-API-Key: YOUR_API_KEY"

Deleting a node removes it and all edges connected to it, but does not delete linked assets or dashboards.

Unlinking Assets or Dashboards​

To unlink an asset or dashboard, delete the edge:

# Find the edge ID
curl -X POST "https://api.beacontower.ai/graph/edges/find" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fromId": "node-67890",
    "toId": "asset-abc123"
  }'

# Delete the edge
curl -X DELETE "https://api.beacontower.ai/graph/edges/edge-xyz" \
  -H "X-API-Key: YOUR_API_KEY"

API Reference​

For complete Graph API documentation, including request schemas, response formats, and error codes, see the API Reference.

Next Steps​

  • Create your first tree to organize assets by location
  • Link dashboards to tree nodes to enable drill-down analytics
  • Explore the Graph API to automate tree management