# ThingsBoard ThingsBoard Assets API
# Source: https://demo.thingsboard.io/v3/api-docs (Apache 2.0)
openapi: 3.1.0
info:
title: ThingsBoard Assets API
description: "ThingsBoard Assets API \u2014 subset of the ThingsBoard REST API (open-source IoT platform). Covers: Asset, Asset Profile, Entity View, Entity Relation."
version: 4.3.0.3DEMO
contact:
name: ThingsBoard team
url: https://thingsboard.io
email: [email protected]
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: asset-controller
description: Asset
- name: asset-profile-controller
description: Asset Profile
- name: entity-view-controller
description: Entity View
- 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
/api/entityViews:
get:
tags:
- entity-view-controller
summary: Get Entity Views by Ids (getEntityViewsByIds)
description: 'Requested entity views must be owned by tenant or assigned to customer which user is performing the request. '
operationId: getEntityViewsByIds
parameters:
- name: entityViewIds
in: query
description: A list of entity view ids, separated by comma ','
required: true
schema:
type: array
items:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/EntityView'
post:
tags:
- entity-view-controller
summary: Find Related Entity Views (findByQuery)
description: 'Returns all entity views that are related to the specific entity. The entity id, relation type, entity view types, depth of the search, and other query parameters defined using complex
''EntityViewSearchQuery'' object. See ''Model'' tab of the Parameters for more info.
Available for users with ''TENANT_ADMIN'' or ''CUSTOMER_USER'' authority.'
operationId: findByQuery_1
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EntityViewSearchQuery'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/EntityView'
/api/entityView:
post:
tags:
- entity-view-controller
summary: Save or Update Entity View (saveEntityView)
description: 'Entity Views limit the degree of exposure of the Device or Asset telemetry and attributes to the Customers. Every Entity View references exactly one entity (device or asset) and defines
telemetry and attribute keys that will be visible to the assigned Customer. As a Tenant Administrator you are able to create multiple EVs per Device or Asset and assign them to different Customers.
See the ''Model'' tab for more details.Remove ''id'', ''tenantId'' and optionally ''customerId'' from the request body example (below) to create new Entity View entity.
Available for users with ''TENANT_ADMIN'' or ''CUSTOMER_USER'' authority.'
operationId: saveEntityView
parameters:
- name: nameConflictPolicy
in: query
description: 'Optional value of name conflict policy. Possible values: FAIL or UNIQUIFY. If omitted, FAIL policy is applied. FAIL policy implies exception will be thrown if an entity with the same
name already exists. UNIQUIFY policy appends a suffix to the entity name, if a name conflict occurs.'
required: false
schema:
type: string
default: FAIL
enum:
- FAIL
- UNIQUIFY
- name: uniquifySeparator
in: query
description: Optional value of name suffix separator used by UNIQUIFY policy. By default, underscore separator is used. For example, strategy is UNIQUIFY, separator is '-'; if a name conflict occurs
for entity name 'test-name', created entity will have name like 'test-name-7fsh4f'.
required: false
schema:
type: string
default: _
- name: uniquifyStrategy
in: query
description: 'Optional value of uniquify strategy used by UNIQUIFY policy. Possible values: RANDOM or INCREMENTAL. By default, RANDOM strategy is used, which means random alphanumeric string will
be added as a suffix to entity name. INCREMENTAL implies the first possible number starting from 1 will be added as a name suffix. For example, strategy is UNIQUIFY, uniquify strategy is INCREMENTAL;
if a name conflict occurs for entity name ''test-name'', created entity will have name like ''test-name-1.'
required: false
schema:
type: string
default: RANDOM
enum:
- RANDOM
- INCREMENTAL
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EntityView'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EntityView'
/api/edge/{edgeId}/entityView/{entityViewId}:
post:
tags:
- entity-view-controller
summary: Assign Entity View to Edge (assignEntityViewToEdge)
description: Creates assignment of an existing entity view to an instance of The Edge. Assignment works in async way - first, notification event pushed to edge service queue on platform. Second, remote
edge service will receive a copy of assignment entity view (Edge will receive this instantly, if it's currently connected, or once it's going to be connected to platform). Third, once entity view
will be delivered to edge service, it's going to be available for usage on remote edge instance.
operationId: assignEntityViewToEdge
parameters:
- name: edgeId
in: path
required: true
schema:
type: string
- name: entityViewId
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EntityView'
delete:
tags:
- entity-view-controller
summary: Unassign Entity View from Edge (unassignEntityViewFromEdge)
description: Clears assignment of the entity view to the edge. Unassignment works in async way - first, 'unassign' notification event pushed to edge queue on platform. Second, remote edge service
will receive an 'unassign' command to remove entity view (Edge will receive this instantly, if it's currently connected, or once it's going to be connected to platform). Third, once 'unassign' command
will be delivered to edge service, it's going to remove entity view locally.
operationId: unassignEntityViewFromEdge
parameters:
- name: edgeId
in: path
required: true
schema:
type: string
- name: entityViewId
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EntityView'
/api/edge/{edgeId}/asset/{assetId}:
post:
tags:
- asset-controller
summary: Assign Asset to Edge (assignAssetToEdge)
description: Creates assignment of an existing asset to an instance of The Edge. Assignment works in async way - first, notification event pushed to edge service queue on platform. Second, remote
edge service will receive a copy of assignment asset (Edge will receive this instantly, if it's currently connected, or once it's going to be connected to platform). Third, once asset will be delivered
to edge service, it's going to be available for usage on remote edge instance.
operationId: assignAssetToEdge
parameters:
- name: edgeId
in: path
description: A string value representing the edge id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
- name: assetId
in: path
description: A string value representing the asset id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Asset'
delete:
tags:
- asset-controller
summary: Unassign Asset from Edge (unassignAssetFromEdge)
description: Clears assignment of the asset to the edge. Unassignment works in async way - first, 'unassign' notification event pushed to edge queue on platform. Second, remote edge service will receive
an 'unassign' command to remove asset (Edge will receive this instantly, if it's currently connected, or once it's going to be connected to platform). Third, once 'unassign' command will be delivered
to edge service, it's going to remove asset locally.
operationId: unassignAssetFromEdge
parameters:
- name: edgeId
in: path
description: A string value representing the edge id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
- name: assetId
in: path
description: A string value representing the asset id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Asset'
/api/customer/{customerId}/entityView/{entityViewId}:
post:
tags:
- entity-view-controller
summary: Assign Entity View to Customer (assignEntityViewToCustomer)
description: 'Creates assignment of the Entity View to customer. Customer will be able to query Entity View afterwards.
Available for users with ''TENANT_ADMIN'' authority.'
operationId: assignEntityViewToCustomer
parameters:
- name: customerId
in: path
description: A string value representing the customer id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
- name: entityViewId
in: path
description: A string value representing the entity view id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EntityView'
/api/customer/{customerId}/asset/{assetId}:
post:
tags:
- asset-controller
summary: Assign Asset to Customer (assignAssetToCustomer)
description: 'Creates assignment of the asset to customer. Customer will be able to query asset afterwards.
Available for users with ''TENANT_ADMIN'' authority.'
operationId: assignAssetToCustomer
parameters:
- name: customerId
in: path
description: A string value representing the customer id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
- name: assetId
in: path
description: A string value representing the asset id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Asset'
/api/customer/public/entityView/{entityViewId}:
post:
tags:
- entity-view-controller
summary: Make Entity View Publicly Available (assignEntityViewToPublicCustomer)
description: 'Entity View will be available for non-authorized (not logged-in) users. This is useful to create dashboards that you plan to share/embed on a publicly available website. However, users
that are logged-in and belong to different tenant will not be able to access the entity view.
Available for users with ''TENANT_ADMIN'' authority.'
operationId: assignEntityViewToPublicCustomer
parameters:
- name: entityViewId
in: path
description: A string value representing the entity view id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EntityView'
/api/customer/public/asset/{assetId}:
post:
tags:
- asset-controller
summary: Make Asset Publicly Available (assignAssetToPublicCustomer)
description: 'Asset will be available for non-authorized (not logged-in) users. This is useful to create dashboards that you plan to share/embed on a publicly available website. However, users that
are logged-in and belong to different tenant will not be able to access the asset.
Available for users with ''TENANT_ADMIN'' authority.'
operationId: assignAssetToPublicCustomer
parameters:
- name: assetId
in: path
description: A string value representing the asset id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Asset'
/api/assets:
get:
tags:
- asset-controller
summary: Get Assets by Ids (getAssetsByIds)
description: 'Requested assets must be owned by tenant or assigned to customer which user is performing the request. '
operationId: getAssetsByIds
parameters:
- name: assetIds
in: query
description: A list of assets ids, separated by comma ','
required: true
schema:
type: array
items:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Asset'
post:
tags:
- asset-controller
summary: Find Related Assets (findByQuery)
description: Returns all assets that are related to the specific entity. The entity id, relation type, asset types, depth of the search, and other query parameters defined using complex 'AssetSearchQuery'
object. See 'Model' tab of the Parameters for more info.
operationId: findByQuery_4
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AssetSearchQuery'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Asset'
/api/asset:
post:
tags:
- asset-controller
summary: Create or Update Asset (saveAsset)
description: "Creates or Updates the Asset. When creating asset, platform generates Asset Id as [time-based UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_1_(date-time_and_MAC_address)).\
\ The newly created Asset id will be present in the response. Specify existing Asset id to update the asset. Referencing non-existing Asset Id will cause 'Not Found' error. Remove 'id', 'tenantId'\
\ and optionally 'customerId' from the request body example (below) to create new Asset entity. \n\nAvailable for users with 'TENANT_ADMIN' or 'CUSTOMER_USER' authority."
operationId: saveAsset
parameters:
- name: nameConflictPolicy
in: query
description: 'Optional value of name conflict policy. Possible values: FAIL or UNIQUIFY. If omitted, FAIL policy is applied. FAIL policy implies exception will be thrown if an entity with the same
name already exists. UNIQUIFY policy appends a suffix to the entity name, if a name conflict occurs.'
required: false
schema:
# --- truncated at 32 KB (109 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/thingsboard/refs/heads/main/openapi/thingsboard-assets-openapi.yml