Relations

Relations connect two entities within the same Tenant, modeling real-world relationships such as hierarchy, ownership, or dependency.

Each relation consists of:

• from — source entity (entity type + UUID)
• to — target entity (entity type + UUID)
• type — a free-text string identifying the relationship kind (e.g., Contains)
• additionalInfo — optional JSON object for custom metadata

Relations have no timestamp — they represent a structural link, not an event.

Example:

{
  "from": { "entityType": "ASSET", "id": "156c853f-89b1-321b-635j-y8febb2784h4" },
  "to":   { "entityType": "DEVICE", "id": "784f394c-42b6-435a-983c-b7beff2784f9" },
  "type": "Contains",
  "additionalInfo": {}
}

A relation always flows from a source entity (From) to a target entity (To):

Direction matters when querying: fetching relations from an entity lists its children; fetching relations to an entity reveals its parents.

The type is a free-text string — use built-in conventions or define your own:

Any string is valid — ThingsBoard places no restrictions on type names.

The Contains relation naturally models parent–child structures:

Querying relations from Region A returns Field A and Field B. Querying relations to Moisture Sensor reveals Field A as its parent.

1. Open the entity details page.
2. Navigate to the Relations tab.
3. Select the direction: From (this entity is the source) or To (this entity is the target).
4. Click + to open the Add relation dialog.
5. Enter the Relation type — choose a built-in value such as Contains or type any custom string.
6. Select the target entity.
7. Optionally fill in Additional info (JSON) for metadata.
8. Click Add.

Relations can be created, queried, and deleted via the REST API. Authenticate using a JWT token in the X-Authorization header. Separate endpoints are available for querying by direction (from/to) and filtering by entity type or relation type.