openapi: 3.1.0 info: title: ThingsBoard Admin admin-controller entity-relation-controller API description: 'ThingsBoard Admin API — subset of the ThingsBoard REST API (open-source IoT platform). Covers: Admin, Audit Log, Event, Usage Info, Queue, Queue Stats, Mail Config Template, Qr Code Settings, Job.' version: 4.3.0.3DEMO contact: name: ThingsBoard team url: https://thingsboard.io email: info@thingsboard.io license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0 servers: - url: https://demo.thingsboard.io description: ThingsBoard Live Demo - url: http://localhost:8080 description: Local ThingsBoard server tags: - name: entity-relation-controller description: Entity Relation paths: /api/v2/relation: post: tags: - entity-relation-controller summary: Create Relation (saveRelationV2) description: "Creates or updates a relation between two entities in the platform. Relations unique key is a combination of from/to entity id and relation type group and relation type. \n\nIf the user has the authority of 'System Administrator', the server checks that 'from' and 'to' entities are owned by the sysadmin. If the user has the authority of 'Tenant Administrator', the server checks that 'from' and 'to' entities are owned by the same tenant. If the user has the authority of 'Customer User', the server checks that the 'from' and 'to' entities are assigned to the same customer." operationId: saveRelationV2 requestBody: content: application/json: schema: $ref: '#/components/schemas/EntityRelation' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/EntityRelation' delete: tags: - entity-relation-controller summary: Delete Relation (deleteRelationV2) description: "Deletes a relation between two entities in the platform. \n\nIf the user has the authority of 'System Administrator', the server checks that 'from' and 'to' entities are owned by the sysadmin. If the user has the authority of 'Tenant Administrator', the server checks that 'from' and 'to' entities are owned by the same tenant. If the user has the authority of 'Customer User', the server checks that the 'from' and 'to' entities are assigned to the same customer." operationId: deleteRelationV2 parameters: - name: fromId in: query description: A string value representing the entity id. For example, '784f394c-42b6-435a-983c-b7beff2784f9' required: true schema: type: string - name: fromType in: query description: A string value representing the entity type. For example, 'DEVICE' required: true schema: type: string - name: relationType in: query description: A string value representing relation type between entities. For example, 'Contains', 'Manages'. It can be any string value. required: true schema: type: string - name: relationTypeGroup in: query description: A string value representing relation type group. For example, 'COMMON' required: false schema: type: string - name: toId in: query description: A string value representing the entity id. For example, '784f394c-42b6-435a-983c-b7beff2784f9' required: true schema: type: string - name: toType in: query description: A string value representing the entity type. For example, 'DEVICE' required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/EntityRelation' /api/relations: get: tags: - entity-relation-controller summary: Get List of Relations (findByFrom) description: "Returns list of relation objects for the specified entity by the 'from' direction and relation type. \n\nIf the user has the authority of 'System Administrator', the server checks that the entity is owned by the sysadmin. If the user has the authority of 'Tenant Administrator', the server checks that the entity is owned by the same tenant. If the user has the authority of 'Customer User', the server checks that the entity is assigned to the same customer." operationId: findByTo parameters: - name: toId in: query description: A string value representing the entity id. For example, '784f394c-42b6-435a-983c-b7beff2784f9' required: true schema: type: string - name: toType in: query description: A string value representing the entity type. For example, 'DEVICE' required: true schema: type: string - name: relationTypeGroup in: query description: A string value representing relation type group. For example, 'COMMON' required: false schema: type: string - name: relationType in: query description: A string value representing relation type between entities. For example, 'Contains', 'Manages'. It can be any string value. required: true schema: type: string - name: fromId in: query description: A string value representing the entity id. For example, '784f394c-42b6-435a-983c-b7beff2784f9' required: true schema: type: string - name: fromType in: query description: A string value representing the entity type. For example, 'DEVICE' required: true schema: type: string responses: '200': description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/EntityRelation' post: tags: - entity-relation-controller summary: Find Related Entities (findByQuery) description: Returns all entities that are related to the specific entity. The entity id, relation type, entity types, depth of the search, and other query parameters defined using complex 'EntityRelationsQuery' object. See 'Model' tab of the Parameters for more info. operationId: findByQuery requestBody: content: application/json: schema: $ref: '#/components/schemas/EntityRelationsQuery' required: true responses: '200': description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/EntityRelation' delete: tags: - entity-relation-controller summary: Delete Common Relations (deleteCommonRelations) description: "Deletes all the relations ('from' and 'to' direction) for the specified entity and relation type group: 'COMMON'. \n\nIf the user has the authority of 'System Administrator', the server checks that the entity is owned by the sysadmin. If the user has the authority of 'Tenant Administrator', the server checks that the entity is owned by the same tenant. If the user has the authority of 'Customer User', the server checks that the entity is assigned to the same customer." operationId: deleteRelations parameters: - name: entityId in: query description: A string value representing the entity id. For example, '784f394c-42b6-435a-983c-b7beff2784f9' required: true schema: type: string - name: entityType in: query description: A string value representing the entity type. For example, 'DEVICE' required: true schema: type: string responses: '200': description: OK /api/relations/info: get: tags: - entity-relation-controller summary: Get List of Relation Infos (findInfoByFrom) description: "Returns list of relation info objects for the specified entity by the 'from' direction. \n\nIf the user has the authority of 'System Administrator', the server checks that the entity is owned by the sysadmin. If the user has the authority of 'Tenant Administrator', the server checks that the entity is owned by the same tenant. If the user has the authority of 'Customer User', the server checks that the entity is assigned to the same customer. Relation Info is an extension of the default Relation object that contains information about the 'from' and 'to' entity names. " operationId: findInfoByTo parameters: - name: toId in: query description: A string value representing the entity id. For example, '784f394c-42b6-435a-983c-b7beff2784f9' required: true schema: type: string - name: toType in: query description: A string value representing the entity type. For example, 'DEVICE' required: true schema: type: string - name: relationTypeGroup in: query description: A string value representing relation type group. For example, 'COMMON' required: false schema: type: string - name: fromId in: query description: A string value representing the entity id. For example, '784f394c-42b6-435a-983c-b7beff2784f9' required: true schema: type: string - name: fromType in: query description: A string value representing the entity type. For example, 'DEVICE' required: true schema: type: string responses: '200': description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/EntityRelationInfo' post: tags: - entity-relation-controller summary: Find Related Entity Infos (findInfoByQuery) description: 'Returns all entity infos that are related to the specific entity. The entity id, relation type, entity types, depth of the search, and other query parameters defined using complex ''EntityRelationsQuery'' object. See ''Model'' tab of the Parameters for more info. Relation Info is an extension of the default Relation object that contains information about the ''from'' and ''to'' entity names. ' operationId: findInfoByQuery requestBody: content: application/json: schema: $ref: '#/components/schemas/EntityRelationsQuery' required: true responses: '200': description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/EntityRelationInfo' /api/relation: get: tags: - entity-relation-controller summary: Get Relation (getRelation) description: "Returns relation object between two specified entities if present. Otherwise throws exception. \n\nIf the user has the authority of 'System Administrator', the server checks that 'from' and 'to' entities are owned by the sysadmin. If the user has the authority of 'Tenant Administrator', the server checks that 'from' and 'to' entities are owned by the same tenant. If the user has the authority of 'Customer User', the server checks that the 'from' and 'to' entities are assigned to the same customer." operationId: getRelation parameters: - name: fromId in: query description: A string value representing the entity id. For example, '784f394c-42b6-435a-983c-b7beff2784f9' required: true schema: type: string - name: fromType in: query description: A string value representing the entity type. For example, 'DEVICE' required: true schema: type: string - name: relationType in: query description: A string value representing relation type between entities. For example, 'Contains', 'Manages'. It can be any string value. required: true schema: type: string - name: relationTypeGroup in: query description: A string value representing relation type group. For example, 'COMMON' required: false schema: type: string - name: toId in: query description: A string value representing the entity id. For example, '784f394c-42b6-435a-983c-b7beff2784f9' required: true schema: type: string - name: toType in: query description: A string value representing the entity type. For example, 'DEVICE' required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/EntityRelation' post: tags: - entity-relation-controller summary: Create Relation (saveRelation) description: "Creates or updates a relation between two entities in the platform. Relations unique key is a combination of from/to entity id and relation type group and relation type. \n\nIf the user has the authority of 'System Administrator', the server checks that 'from' and 'to' entities are owned by the sysadmin. If the user has the authority of 'Tenant Administrator', the server checks that 'from' and 'to' entities are owned by the same tenant. If the user has the authority of 'Customer User', the server checks that the 'from' and 'to' entities are assigned to the same customer." operationId: saveRelation requestBody: content: application/json: schema: $ref: '#/components/schemas/EntityRelation' required: true responses: '200': description: OK delete: tags: - entity-relation-controller summary: Delete Relation (deleteRelation) description: "Deletes a relation between two entities in the platform. \n\nIf the user has the authority of 'System Administrator', the server checks that 'from' and 'to' entities are owned by the sysadmin. If the user has the authority of 'Tenant Administrator', the server checks that 'from' and 'to' entities are owned by the same tenant. If the user has the authority of 'Customer User', the server checks that the 'from' and 'to' entities are assigned to the same customer." operationId: deleteRelation parameters: - name: fromId in: query description: A string value representing the entity id. For example, '784f394c-42b6-435a-983c-b7beff2784f9' required: true schema: type: string - name: fromType in: query description: A string value representing the entity type. For example, 'DEVICE' required: true schema: type: string - name: relationType in: query description: A string value representing relation type between entities. For example, 'Contains', 'Manages'. It can be any string value. required: true schema: type: string - name: relationTypeGroup in: query description: A string value representing relation type group. For example, 'COMMON' required: false schema: type: string - name: toId in: query description: A string value representing the entity id. For example, '784f394c-42b6-435a-983c-b7beff2784f9' required: true schema: type: string - name: toType in: query description: A string value representing the entity type. For example, 'DEVICE' required: true schema: type: string responses: '200': description: OK components: schemas: JsonNode: description: A value representing the any type (object or primitive) examples: - {} EntityRelationInfo: type: object properties: from: $ref: '#/components/schemas/EntityId' description: JSON object with [from] Entity Id. to: $ref: '#/components/schemas/EntityId' description: JSON object with [to] Entity Id. type: type: string description: String value of relation type. example: Contains minLength: 1 typeGroup: type: string description: Represents the type group of the relation. enum: - COMMON - DASHBOARD - RULE_CHAIN - RULE_NODE - EDGE - EDGE_AUTO_ASSIGN_RULE_CHAIN example: COMMON version: type: integer format: int64 fromName: type: string description: Name of the entity for [from] direction. example: A4B72CCDFF33 readOnly: true toName: type: string description: Name of the entity for [to] direction. example: A4B72CCDFF35 readOnly: true additionalInfo: $ref: '#/components/schemas/JsonNode' description: Additional parameters of the relation required: - from - to - type - typeGroup EntityRelationsQuery: type: object description: A JSON value representing the entity relations query object. properties: parameters: $ref: '#/components/schemas/RelationsSearchParameters' description: Main search parameters. filters: type: array description: Main filters. items: $ref: '#/components/schemas/RelationEntityTypeFilter' EntityRelation: type: object description: A JSON value representing the relation. properties: from: $ref: '#/components/schemas/EntityId' description: JSON object with [from] Entity Id. to: $ref: '#/components/schemas/EntityId' description: JSON object with [to] Entity Id. type: type: string description: String value of relation type. example: Contains minLength: 1 typeGroup: type: string description: Represents the type group of the relation. enum: - COMMON - DASHBOARD - RULE_CHAIN - RULE_NODE - EDGE - EDGE_AUTO_ASSIGN_RULE_CHAIN example: COMMON version: type: integer format: int64 additionalInfo: $ref: '#/components/schemas/JsonNode' description: Additional parameters of the relation required: - from - to - type - typeGroup RelationsSearchParameters: type: object properties: rootId: type: string format: uuid description: Root entity id to start search from. example: 784f394c-42b6-435a-983c-b7beff2784f9 rootType: type: string description: Type of the root entity. enum: - TENANT - CUSTOMER - USER - DASHBOARD - ASSET - DEVICE - ALARM - RULE_CHAIN - RULE_NODE - ENTITY_VIEW - WIDGETS_BUNDLE - WIDGET_TYPE - TENANT_PROFILE - DEVICE_PROFILE - ASSET_PROFILE - API_USAGE_STATE - TB_RESOURCE - OTA_PACKAGE - EDGE - RPC - QUEUE - NOTIFICATION_TARGET - NOTIFICATION_TEMPLATE - NOTIFICATION_REQUEST - NOTIFICATION - NOTIFICATION_RULE - QUEUE_STATS - OAUTH2_CLIENT - DOMAIN - MOBILE_APP - MOBILE_APP_BUNDLE - CALCULATED_FIELD - JOB - ADMIN_SETTINGS - AI_MODEL - API_KEY direction: type: string description: Type of the root entity. enum: - FROM - TO relationTypeGroup: type: string description: Type of the relation. enum: - COMMON - DASHBOARD - RULE_CHAIN - RULE_NODE - EDGE - EDGE_AUTO_ASSIGN_RULE_CHAIN maxLevel: type: integer format: int32 description: Maximum level of the search depth. fetchLastLevelOnly: type: boolean description: Fetch entities that match the last level of search. Useful to find Devices that are strictly 'maxLevel' relations away from the root entity. EntityId: type: object properties: id: type: string format: uuid description: ID of the entity, time-based UUID v1 example: 784f394c-42b6-435a-983c-b7beff2784f9 entityType: type: string enum: - TENANT - CUSTOMER - USER - DASHBOARD - ASSET - DEVICE - ALARM - RULE_CHAIN - RULE_NODE - ENTITY_VIEW - WIDGETS_BUNDLE - WIDGET_TYPE - TENANT_PROFILE - DEVICE_PROFILE - ASSET_PROFILE - API_USAGE_STATE - TB_RESOURCE - OTA_PACKAGE - EDGE - RPC - QUEUE - NOTIFICATION_TARGET - NOTIFICATION_TEMPLATE - NOTIFICATION_REQUEST - NOTIFICATION - NOTIFICATION_RULE - QUEUE_STATS - OAUTH2_CLIENT - DOMAIN - MOBILE_APP - MOBILE_APP_BUNDLE - CALCULATED_FIELD - JOB - ADMIN_SETTINGS - AI_MODEL - API_KEY example: DEVICE required: - entityType - id RelationEntityTypeFilter: type: object properties: relationType: type: string description: Type of the relation between root entity and other entity (e.g. 'Contains' or 'Manages'). example: Contains entityTypes: type: array description: Array of entity types to filter the related entities (e.g. 'DEVICE', 'ASSET'). items: type: string enum: - TENANT - CUSTOMER - USER - DASHBOARD - ASSET - DEVICE - ALARM - RULE_CHAIN - RULE_NODE - ENTITY_VIEW - WIDGETS_BUNDLE - WIDGET_TYPE - TENANT_PROFILE - DEVICE_PROFILE - ASSET_PROFILE - API_USAGE_STATE - TB_RESOURCE - OTA_PACKAGE - EDGE - RPC - QUEUE - NOTIFICATION_TARGET - NOTIFICATION_TEMPLATE - NOTIFICATION_REQUEST - NOTIFICATION - NOTIFICATION_RULE - QUEUE_STATS - OAUTH2_CLIENT - DOMAIN - MOBILE_APP - MOBILE_APP_BUNDLE - CALCULATED_FIELD - JOB - ADMIN_SETTINGS - AI_MODEL - API_KEY negate: type: boolean description: Negate relation type between root entity and other entity. securitySchemes: HTTP login form: type: http description: Enter Username / Password scheme: loginPassword bearerFormat: /api/auth/login|X-Authorization API key form: type: apiKey description: 'Enter the API key value with ''ApiKey'' prefix in format: **ApiKey ** Example: **ApiKey tb_5te51SkLRYpjGrujUGwqkjFvooWBlQpVe2An2Dr3w13wjfxDW**
**NOTE**: Use only ONE authentication method at a time. If both are authorized, JWT auth takes the priority.
' name: X-Authorization in: header