openapi: 3.1.0
info:
title: ThingsBoard Admin admin-controller asset-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: asset-controller
description: Asset
paths:
/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}/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/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:
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:
description: A JSON value representing the asset.
content:
application/json:
schema:
$ref: '#/components/schemas/Asset'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Asset'
/api/asset/bulk_import:
post:
tags:
- asset-controller
summary: Import the Bulk of Assets (processAssetsBulkImport)
description: There's an ability to import the bulk of assets using the only .csv file.
operationId: processAssetsBulkImport
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BulkImportRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BulkImportResultAsset'
/api/tenant/assets:
get:
tags:
- asset-controller
summary: Get Tenant Asset (getTenantAsset)
description: 'Requested asset must be owned by tenant that the user belongs to. Asset name is an unique property of asset. So it can be used to identify the asset.
Available for users with ''TENANT_ADMIN'' authority.'
operationId: getTenantAssets
parameters:
- name: pageSize
in: query
description: Maximum amount of entities in a one page
required: true
schema:
type: integer
format: int32
- name: page
in: query
description: Sequence number of page starting from 0
required: true
schema:
type: integer
format: int32
- name: type
in: query
description: Asset type
required: false
schema:
type: string
- name: textSearch
in: query
description: The case insensitive 'substring' filter based on the asset name.
required: false
schema:
type: string
- name: sortProperty
in: query
description: Property of entity to sort by
required: false
schema:
type: string
enum:
- createdTime
- name
- type
- label
- customerTitle
- name: sortOrder
in: query
description: Sort order. ASC (ASCENDING) or DESC (DESCENDING)
required: false
schema:
type: string
enum:
- ASC
- DESC
- name: assetName
in: query
description: A string value representing the Asset name.
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Asset'
- $ref: '#/components/schemas/PageDataAsset'
/api/tenant/assetInfos:
get:
tags:
- asset-controller
summary: Get Tenant Asset Infos (getTenantAssetInfos)
description: "Returns a page of assets info objects owned by tenant. You can specify parameters to filter the results. The result is wrapped with PageData object that allows you to iterate over result set using pagination. See response schema for more details. Asset Info is an extension of the default Asset object that contains information about the assigned customer name. \n\nAvailable for users with 'TENANT_ADMIN' authority."
operationId: getTenantAssetInfos
parameters:
- name: pageSize
in: query
description: Maximum amount of entities in a one page
required: true
schema:
type: integer
format: int32
- name: page
in: query
description: Sequence number of page starting from 0
required: true
schema:
type: integer
format: int32
- name: type
in: query
description: Asset type
required: false
schema:
type: string
- name: assetProfileId
in: query
description: A string value representing the asset profile id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: false
schema:
type: string
- name: textSearch
in: query
description: The case insensitive 'substring' filter based on the asset name.
required: false
schema:
type: string
- name: sortProperty
in: query
description: Property of entity to sort by
required: false
schema:
type: string
enum:
- createdTime
- name
- type
- label
- customerTitle
- name: sortOrder
in: query
description: Sort order. ASC (ASCENDING) or DESC (DESCENDING)
required: false
schema:
type: string
enum:
- ASC
- DESC
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PageDataAssetInfo'
/api/edge/{edgeId}/assets:
get:
tags:
- asset-controller
summary: Get Assets Assigned to Edge (getEdgeAssets)
description: 'Returns a page of assets assigned to edge. You can specify parameters to filter the results. The result is wrapped with PageData object that allows you to iterate over result set using pagination. See response schema for more details. '
operationId: getEdgeAssets
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: pageSize
in: query
description: Maximum amount of entities in a one page
required: true
schema:
type: integer
format: int32
- name: page
in: query
description: Sequence number of page starting from 0
required: true
schema:
type: integer
format: int32
- name: type
in: query
description: Asset type
required: false
schema:
type: string
- name: textSearch
in: query
description: The case insensitive 'substring' filter based on the asset name.
required: false
schema:
type: string
- name: sortProperty
in: query
description: Property of entity to sort by
required: false
schema:
type: string
enum:
- createdTime
- name
- type
- label
- customerTitle
- name: sortOrder
in: query
description: Sort order. ASC (ASCENDING) or DESC (DESCENDING)
required: false
schema:
type: string
enum:
- ASC
- DESC
- name: startTime
in: query
description: Timestamp. Assets with creation time before it won't be queried
required: false
schema:
type: integer
format: int64
- name: endTime
in: query
description: Timestamp. Assets with creation time after it won't be queried
required: false
schema:
type: integer
format: int64
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PageDataAsset'
/api/customer/{customerId}/assets:
get:
tags:
- asset-controller
summary: Get Customer Assets (getCustomerAssets)
description: 'Returns a page of assets objects assigned to customer. You can specify parameters to filter the results. The result is wrapped with PageData object that allows you to iterate over result set using pagination. See response schema for more details. '
operationId: getCustomerAssets
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: pageSize
in: query
description: Maximum amount of entities in a one page
required: true
schema:
type: integer
format: int32
- name: page
in: query
description: Sequence number of page starting from 0
required: true
schema:
type: integer
format: int32
- name: type
in: query
description: Asset type
required: false
schema:
type: string
- name: textSearch
in: query
description: The case insensitive 'substring' filter based on the asset name.
required: false
schema:
type: string
- name: sortProperty
in: query
description: Property of entity to sort by
required: false
schema:
type: string
enum:
- createdTime
- name
- type
- label
- customerTitle
- name: sortOrder
in: query
description: Sort order. ASC (ASCENDING) or DESC (DESCENDING)
required: false
schema:
type: string
enum:
- ASC
- DESC
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PageDataAsset'
/api/customer/{customerId}/assetInfos:
get:
tags:
- asset-controller
summary: Get Customer Asset Infos (getCustomerAssetInfos)
description: 'Returns a page of assets info objects assigned to customer. You can specify parameters to filter the results. The result is wrapped with PageData object that allows you to iterate over result set using pagination. See response schema for more details. Asset Info is an extension of the default Asset object that contains information about the assigned customer name. '
operationId: getCustomerAssetInfos
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: pageSize
in: query
description: Maximum amount of entities in a one page
required: true
schema:
type: integer
format: int32
- name: page
in: query
description: Sequence number of page starting from 0
required: true
schema:
type: integer
format: int32
- name: type
in: query
description: Asset type
required: false
schema:
type: string
- name: assetProfileId
in: query
description: A string value representing the asset profile id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: false
schema:
type: string
- name: textSearch
in: query
description: The case insensitive 'substring' filter based on the asset name.
required: false
schema:
type: string
- name: sortProperty
in: query
description: Property of entity to sort by
required: false
schema:
type: string
enum:
- createdTime
- name
- type
- label
- customerTitle
- name: sortOrder
in: query
description: Sort order. ASC (ASCENDING) or DESC (DESCENDING)
required: false
schema:
type: string
enum:
- ASC
- DESC
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PageDataAssetInfo'
/api/asset/{assetId}:
get:
tags:
- asset-controller
summary: Get Asset (getAssetById)
description: 'Fetch the Asset object based on the provided Asset Id. If the user has the authority of ''Tenant Administrator'', the server checks that the asset is owned by the same tenant. If the user has the authority of ''Customer User'', the server checks that the asset is assigned to the same customer.
Available for users with ''TENANT_ADMIN'' or ''CUSTOMER_USER'' authority.'
operationId: getAssetById
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'
delete:
tags:
- asset-controller
summary: Delete Asset (deleteAsset)
description: 'Deletes the asset and all the relations (from and to the asset). Referencing non-existing asset Id will cause an error.
Available for users with ''TENANT_ADMIN'' or ''CUSTOMER_USER'' authority.'
operationId: deleteAsset
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
/api/asset/types:
get:
tags:
- asset-controller
summary: Get Asset Types (getAssetTypes)
description: 'Deprecated. See ''getAssetProfileNames'' API from Asset Profile Controller instead.
Available for users with ''TENANT_ADMIN'' or ''CUSTOMER_USER'' authority.'
operationId: getAssetTypes
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/EntitySubtype'
deprecated: true
/api/asset/info/{assetId}:
get:
tags:
- asset-controller
summary: Get Asset Info (getAssetInfoById)
description: "Fetch the Asset Info object based on the provided Asset Id. If the user has the authority of 'Tenant Administrator', the server checks that the asset is owned by the same tenant. If the user has the authority of 'Customer User', the server checks that the asset is assigned to the same customer. Asset Info is an extension of the default Asset object that contains information about the assigned customer name. \n\nAvailable for users with 'TENANT_ADMIN' or 'CUSTOMER_USER' authority."
operationId: getAssetInfoById
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/AssetInfo'
/api/customer/asset/{assetId}:
delete:
tags:
- asset-controller
summary: Unassign Asset from Customer (unassignAssetFromCustomer)
description: 'Clears assignment of the asset to customer. Customer will not be able to query asset afterwards.
Available for users with ''TENANT_ADMIN'' authority.'
operationId: unassignAssetFromCustomer
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'
components:
schemas:
AssetInfo:
type: object
properties:
id:
$ref: '#/components/schemas/AssetId'
description: JSON object with the asset Id. Specify this field to update the asset. Referencing non-existing asset Id will cause error. Omit this field to create new asset.
createdTime:
type: integer
format: int64
description: Timestamp of the asset creation, in milliseconds
example: 1609459200000
readOnly: true
tenantId:
$ref: '#/components/schemas/TenantId'
description: JSON object with Tenant Id.
readOnly: true
customerId:
$ref: '#/components/schemas/CustomerId'
description: JSON object with Customer Id. Use 'assignAssetToCustomer' to change the Customer Id.
readOnly: true
name:
type: string
description: Unique Asset Name in scope of Tenant
example: Empire State Building
type:
type: string
description: Asset type
example: Building
label:
type: string
description: Label that may be used in widgets
example: NY Building
assetProfileId:
$ref: '#/components/schemas/AssetProfileId'
description: JSON object with Asset Profile Id.
version:
type: integer
format: int64
customerTitle:
type: string
description: Title of the Customer that owns the asset.
readOnly: true
customerIsPublic:
type: boolean
description: Indicates special 'Public' Customer that is auto-generated to use the assets on public dashboards.
readOnly: true
assetProfileName:
type: string
description: Name of the corresponding Asset Profile.
readOnly: true
additionalInfo:
$ref: '#/components/schemas/JsonNode'
description: Additional parameters of the asset
required:
- name
AssetProfileId:
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
description: string
enum:
- ASSET_PROFILE
example: ASSET_PROFILE
required:
- entityType
- id
PageDataAssetInfo:
type: object
properties:
data:
type: array
description: Array of the entities
items:
$ref: '#/components/schemas/AssetInfo'
readOnly: true
totalPages:
type: integer
format: int32
description: Total number of available pages. Calculated based on the 'pageSize' request parameter and total number of entities that match search criteria
readOnly: true
totalElements:
type: integer
format: int64
description: Total number of elements in all available pages
readOnly: true
hasNext:
type: boolean
description: '''false'' value indicates the end of the result set'
readOnly: true
JsonNode:
description: A value representing the any type (object or primitive)
examples:
- {}
Asset:
type: object
properties:
id:
$ref: '#/components/schemas/AssetId'
description: JSON object with the asset Id. Specify this field to update the asset. Referencing non-existing asset Id will cause error. Omit this field to create new asset.
createdTime:
type: integer
format: int64
description: Timestamp of the asset creation, in milliseconds
example: 1609459200000
readOnly: true
tenantId:
$ref: '#/components/schemas/TenantId'
description: JSON object with Tenant Id.
readOnly: true
customerId:
$ref: '#/components/schemas/CustomerId'
description: JSON object with Customer Id. Use 'assignAssetToCustomer' to change the Customer Id.
readOnly: true
name:
type: string
description: Unique Asset Name in scope of Tenant
example: Empire State Building
type:
type: string
description: Asset type
example: Building
label:
type: string
description: Label that may be used in widgets
example: NY Building
assetProfileId:
$ref: '#/components/schemas/AssetProfileId'
description: JSON object with Asset Profile Id.
version:
type: integer
format: int64
additionalInfo:
$ref: '#/components/schemas/JsonNode'
description: Additional parameters of the asset
required:
- name
BulkImportRequest:
type: object
properties:
file:
type: string
mapping:
$ref: '#/components/schemas/Mapping'
AssetSearchQuery:
type: object
properties:
parameters:
$ref: '#/components/schemas/RelationsSearchParameters'
description: Main search parameters.
relationType:
type: string
description: Type of the relation between root entity and asset (e.g. 'Contains' or 'Manages').
assetTypes:
type: array
description: Array of asset types to filter the related entities (e.g. 'Building', 'Vehicle').
items:
type: string
ColumnMapping:
type: object
properties:
type:
type: string
enum:
- NAME
- TYPE
- LABEL
- SHARED_ATTRIBUTE
- SERVER_ATTRIBUTE
- TIMESERIES
- ACCESS_TOKEN
- X509
- MQTT_CLIENT_ID
- MQTT_USER_NAME
- MQTT_PASSWORD
- LWM2M_CLIENT_ENDPOINT
- LWM2M_CLIENT_SECURITY_CONFIG_MODE
- LWM2M_CLIENT_IDENTITY
- LWM2M_CLIENT_KEY
- LWM2M_CLIENT_CERT
- LWM2M_BOOTSTRAP_SERVER_SECURITY_MODE
- LWM2M_BOOTSTRAP_SERVER_PUBLIC_KEY_OR_ID
- LWM2M_BOOTSTRAP_SERVER_SECRET_KEY
- LWM2M_SERVER_SECURITY_MODE
- LWM2M_SERVER_CLIENT_PUBLIC_KEY_OR_ID
- LWM2M_SERVER_CLIENT_SECRET_KEY
- SNMP_HOST
- SNMP_PORT
- SNMP_VERSION
- SNMP_COMMUNITY_STRING
- IS_GATEWAY
- DESCRIPTION
- ROUTING_KEY
- SECRET
key:
type: string
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
- ENTI
# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/thingsboard/refs/heads/main/openapi/thingsboard-asset-controller-api-openapi.yml