ThingsBoard Dashboards API
Create and manage dashboards, widget bundles, widget types, image resources, and tenant resources that drive the ThingsBoard UI. Includes SCADA dashboards. 57 endpoints.
Create and manage dashboards, widget bundles, widget types, image resources, and tenant resources that drive the ThingsBoard UI. Includes SCADA dashboards. 57 endpoints.
# ThingsBoard ThingsBoard Dashboards API
# Source: https://demo.thingsboard.io/v3/api-docs (Apache 2.0)
openapi: 3.1.0
info:
title: ThingsBoard Dashboards API
description: "ThingsBoard Dashboards API \u2014 subset of the ThingsBoard REST API (open-source IoT platform). Covers: Dashboard, Widget Type, Widgets Bundle, Image, Tb Resource, Ui Settings."
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: dashboard-controller
description: Dashboard
- name: widget-type-controller
description: Widget Type
- name: widgets-bundle-controller
description: Widgets Bundle
- name: image-controller
description: Image
- name: tb-resource-controller
description: Tb Resource
- name: ui-settings-controller
description: Ui Settings
paths:
/api/resource/{id}/info:
put:
tags:
- tb-resource-controller
operationId: updateResourceInfo
parameters:
- name: id
in: path
description: Unique identifier of the Resource to update
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TbResourceInfo'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/TbResourceInfo'
/api/resource/{id}/data:
put:
tags:
- tb-resource-controller
operationId: updateResourceData
parameters:
- name: id
in: path
description: Unique identifier of the Resource to update
required: true
schema:
type: string
format: uuid
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
file:
type: string
format: binary
description: Resource file.
required:
- file
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/TbResourceInfo'
/api/images/{type}/{key}:
get:
tags:
- image-controller
operationId: downloadImage
parameters:
- name: type
in: path
description: 'Type of the image: tenant or system'
required: true
schema:
type: string
enum:
- tenant
- system
- name: key
in: path
description: Image resource key, for example thermostats_dashboard_background.jpeg
required: true
schema:
type: string
- name: If-None-Match
in: header
required: false
schema:
type: string
- name: Accept-Encoding
in: header
required: false
schema:
type: string
responses:
'200':
description: OK
content:
image/*:
schema:
type: string
format: binary
put:
tags:
- image-controller
operationId: updateImage
parameters:
- name: type
in: path
description: 'Type of the image: tenant or system'
required: true
schema:
type: string
enum:
- tenant
- system
- name: key
in: path
description: Image resource key, for example thermostats_dashboard_background.jpeg
required: true
schema:
type: string
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
file:
type: string
format: binary
required:
- file
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/TbResourceInfo'
delete:
tags:
- image-controller
operationId: deleteImage
parameters:
- name: type
in: path
description: 'Type of the image: tenant or system'
required: true
schema:
type: string
enum:
- tenant
- system
- name: key
in: path
description: Image resource key, for example thermostats_dashboard_background.jpeg
required: true
schema:
type: string
- name: force
in: query
required: false
schema:
type: boolean
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/TbImageDeleteResult'
/api/images/{type}/{key}/public/{isPublic}:
put:
tags:
- image-controller
operationId: updateImagePublicStatus
parameters:
- name: type
in: path
description: 'Type of the image: tenant or system'
required: true
schema:
type: string
enum:
- tenant
- system
- name: key
in: path
description: Image resource key, for example thermostats_dashboard_background.jpeg
required: true
schema:
type: string
- name: isPublic
in: path
required: true
schema:
type: boolean
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/TbResourceInfo'
/api/images/{type}/{key}/info:
get:
tags:
- image-controller
operationId: getImageInfo
parameters:
- name: type
in: path
description: 'Type of the image: tenant or system'
required: true
schema:
type: string
enum:
- tenant
- system
- name: key
in: path
description: Image resource key, for example thermostats_dashboard_background.jpeg
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/TbResourceInfo'
put:
tags:
- image-controller
operationId: updateImageInfo
parameters:
- name: type
in: path
description: 'Type of the image: tenant or system'
required: true
schema:
type: string
enum:
- tenant
- system
- name: key
in: path
description: Image resource key, for example thermostats_dashboard_background.jpeg
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TbResourceInfo'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/TbResourceInfo'
/api/image/import:
put:
tags:
- image-controller
operationId: importImage
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceExportData'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/TbResourceInfo'
/api/widgetsBundle:
post:
tags:
- widgets-bundle-controller
summary: Create or Update Widget Bundle (saveWidgetsBundle)
description: 'Create or update the Widget Bundle. Widget Bundle represents a group(bundle) of widgets. Widgets are grouped into bundle by type or use case. When creating the bundle, platform generates
Widget Bundle Id as [time-based UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_1_(date-time_and_MAC_address)). The newly created Widget Bundle Id will be present in the
response. Specify existing Widget Bundle id to update the Widget Bundle. Referencing non-existing Widget Bundle Id will cause ''Not Found'' error.
Widget Bundle alias is unique in the scope of tenant. Special Tenant Id ''13814000-1dd2-11b2-8080-808080808080'' is automatically used if the create bundle request is sent by user with ''SYS_ADMIN''
authority.Remove ''id'', ''tenantId'' from the request body example (below) to create new Widgets Bundle entity.
Available for users with ''SYS_ADMIN'' or ''TENANT_ADMIN'' authority.'
operationId: saveWidgetsBundle
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/WidgetsBundle'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/WidgetsBundle'
/api/widgetsBundle/{widgetsBundleId}/widgetTypes:
post:
tags:
- widgets-bundle-controller
summary: Update Widgets Bundle Widgets Types List (updateWidgetsBundleWidgetTypes)
description: 'Updates widgets bundle widgets list.
Available for users with ''SYS_ADMIN'' or ''TENANT_ADMIN'' authority.'
operationId: updateWidgetsBundleWidgetTypes
parameters:
- name: widgetsBundleId
in: path
description: A string value representing the widget bundle id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: array
description: Ordered list of widget type Ids to be included by widgets bundle
items:
type: string
required: true
responses:
'200':
description: OK
/api/widgetsBundle/{widgetsBundleId}/widgetTypeFqns:
post:
tags:
- widgets-bundle-controller
summary: Update Widgets Bundle Widgets List from Widget Type FQNs List (updateWidgetsBundleWidgetFqns)
description: 'Updates widgets bundle widgets list from widget type FQNs list.
Available for users with ''SYS_ADMIN'' or ''TENANT_ADMIN'' authority.'
operationId: updateWidgetsBundleWidgetFqns
parameters:
- name: widgetsBundleId
in: path
description: A string value representing the widget bundle id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: array
description: Ordered list of widget type FQNs to be included by widgets bundle
items:
type: string
required: true
responses:
'200':
description: OK
/api/widgetType:
get:
tags:
- widget-type-controller
summary: Get Widget Type (getWidgetType)
description: 'Get the Widget Type by FQN. Widget Type represents the template for widget creation. Widget Type and Widget are similar to class and object in OOP theory.
Available for any authorized user. '
operationId: getWidgetTypeByBundleAliasAndTypeAlias
parameters:
- name: isSystem
in: query
description: System or Tenant
required: true
schema:
type: boolean
- name: bundleAlias
in: query
description: Widget Bundle alias
required: true
schema:
type: string
- name: alias
in: query
description: Widget Type alias
required: true
schema:
type: string
- name: fqn
in: query
description: Widget Type fqn
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/WidgetType'
deprecated: true
post:
tags:
- widget-type-controller
summary: Create or Update Widget Type (saveWidgetType)
description: 'Create or update the Widget Type. Widget Type represents the template for widget creation. Widget Type and Widget are similar to class and object in OOP theory. When creating the Widget
Type, platform generates Widget Type Id as [time-based UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_1_(date-time_and_MAC_address)). The newly created Widget Type Id
will be present in the response. Specify existing Widget Type id to update the Widget Type. Referencing non-existing Widget Type Id will cause ''Not Found'' error.
Widget Type fqn is unique in the scope of System or Tenant. Special Tenant Id ''13814000-1dd2-11b2-8080-808080808080'' is automatically used if the create request is sent by user with ''SYS_ADMIN''
authority.Remove ''id'', ''tenantId'' rom the request body example (below) to create new Widget Type entity.
Available for users with ''SYS_ADMIN'' or ''TENANT_ADMIN'' authority.'
operationId: saveWidgetType
parameters:
- name: updateExistingByFqn
in: query
description: Optional boolean parameter indicating whether to update existing widget type by FQN if present instead of creating new one
required: false
schema:
type: boolean
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/WidgetTypeDetails'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/WidgetTypeDetails'
/api/tenant/dashboard/home/info:
get:
tags:
- dashboard-controller
summary: Get Tenant Home Dashboard Info (getTenantHomeDashboardInfo)
description: "Returns the home dashboard info object that is configured as 'homeDashboardId' parameter in the 'additionalInfo' of the corresponding tenant. \n\nAvailable for users with 'TENANT_ADMIN'\
\ authority."
operationId: getTenantHomeDashboardInfo
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/HomeDashboardInfo'
post:
tags:
- dashboard-controller
summary: Update Tenant Home Dashboard Info (getTenantHomeDashboardInfo)
description: "Update the home dashboard assignment for the current tenant. \n\nAvailable for users with 'TENANT_ADMIN' authority."
operationId: setTenantHomeDashboardInfo
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/HomeDashboardInfo'
required: true
responses:
'200':
description: OK
/api/resource:
get:
tags:
- tb-resource-controller
summary: Get Resource Infos by Ids (getSystemOrTenantResourcesByIds)
description: "Returns a page of Resource Info objects owned by tenant or sysadmin. 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. Resource Info is a lightweight object that includes main information about the Resource excluding the heavyweight data.\
\ \n\nAvailable for users with 'SYS_ADMIN' or 'TENANT_ADMIN' authority."
operationId: getResources
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: resourceType
in: query
description: A string value representing the resource type.
required: false
schema:
type: string
enum:
- LWM2M_MODEL
- JKS
- PKCS_12
- JS_MODULE
- name: resourceSubType
in: query
description: A string value representing the resource sub-type.
required: false
schema:
type: string
enum:
- EXTENSION
- MODULE
- name: textSearch
in: query
description: The case insensitive 'substring' filter based on the resource title.
required: false
schema:
type: string
- name: sortProperty
in: query
description: Property of entity to sort by
required: false
schema:
type: string
enum:
- createdTime
- title
- resourceType
- tenantId
- name: sortOrder
in: query
description: Sort order. ASC (ASCENDING) or DESC (DESCENDING)
required: false
schema:
type: string
enum:
- ASC
- DESC
- name: resourceIds
in: query
description: A list of resource ids, separated by comma ','
required: true
schema:
type: array
items:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
oneOf:
- type: array
items:
$ref: '#/components/schemas/TbResourceInfo'
- $ref: '#/components/schemas/PageDataTbResourceInfo'
post:
tags:
- tb-resource-controller
summary: Create or Update Resource (saveResource)
description: "Create or update the Resource. When creating the Resource, platform generates Resource id as [time-based UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_1_(date-time_and_MAC_address)).\
\ The newly created Resource id will be present in the response. Specify existing Resource id to update the Resource. Referencing non-existing Resource Id will cause 'Not Found' error. \n\nResource\
\ combination of the title with the key is unique in the scope of tenant. Remove 'id', 'tenantId' from the request body example (below) to create new Resource entity.\n\nAvailable for users with\
\ 'SYS_ADMIN' or 'TENANT_ADMIN' authority."
operationId: saveResource
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TbResource'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/TbResourceInfo'
deprecated: true
/api/resource/upload:
post:
tags:
- tb-resource-controller
summary: Upload Resource Via Multipart File (uploadResource)
description: "Create the Resource using multipart file upload. \n\nResource combination of the title with the key is unique in the scope of tenant. \n\nAvailable for users with 'SYS_ADMIN' or 'TENANT_ADMIN'\
\ authority."
operationId: uploadResource
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
title:
type: string
description: Resource title.
resourceType:
type: string
description: Resource type.
descriptor:
type: string
description: Resource descriptor (JSON).
resourceSubType:
type: string
description: Resource sub type.
file:
type: string
format: binary
description: Resource file.
required:
- file
- resourceType
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/TbResourceInfo'
/api/image:
post:
tags:
- image-controller
operationId: uploadImage
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
file:
type: string
format: binary
title:
type: string
imageSubType:
type: string
required:
- file
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/TbResourceInfo'
/api/edge/{edgeId}/dashboard/{dashboardId}:
post:
tags:
- dashboard-controller
summary: Assign Dashboard to Edge (assignDashboardToEdge)
description: 'Creates assignment of an existing dashboard 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 dashboard (Edge will receive this instantly, if it''s currently connected, or once it''s going to be connected to platform). Third, once dashboard
will be delivered to edge service, it''s going to be available for usage on remote edge instance.
Available for users with ''TENANT_ADMIN'' authority.'
operationId: assignDashboardToEdge
parameters:
- name: edgeId
in: path
required: true
schema:
type: string
- name: dashboardId
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Dashboard'
delete:
tags:
- dashboard-controller
summary: Unassign Dashboard from Edge (unassignDashboardFromEdge)
description: 'Clears assignment of the dashboard 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 dashboard (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 dashboard locally.
Available for users with ''TENANT_ADMIN'' authority.'
operationId: unassignDashboardFromEdge
parameters:
- name: edgeId
in: path
required: true
schema:
type: string
- name: dashboardId
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Dashboard'
/api/dashboard:
post:
tags:
- dashboard-controller
summary: Create or Update Dashboard (saveDashboard)
description: "Create or update the Dashboard. When creating dashboard, platform generates Dashboard Id as [time-based UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_1_(date-time_and_MAC_address)).\
\ The newly created Dashboard id will be present in the response. Specify existing Dashboard id to update the dashboard. Referencing non-existing dashboard Id will cause 'Not Found' error. Remove\
\ 'id', 'tenantId' and optionally 'customerId' from the request body example (below) to create new Dashboard entity. \n\nAvailable for users with 'TENANT_ADMIN' authority."
operationId: saveDashboard
parameters:
- name: Accept-Encoding
in: header
required: false
schema:
type: string
requestBody:
description: A JSON value representing the dashboard.
content:
application/json:
schema:
$ref: '#/components/schemas/Dashboard'
required: true
responses:
'200':
description: OK
/api/dashboard/{dashboardId}/customers:
post:
tags:
- dashboard-controller
summary: Update the Dashboard Customers (updateDashboardCustomers)
description: "Updates the list of Customers that this Dashboard is assigned to. Removes previous assignments to customers that are not in the provided list. Returns the Dashboard object. \n\nAvailable\
\ for users with 'TENANT_ADMIN' authority."
operationId: updateDashboardCustomers
parameters:
- name: dashboardId
in: path
description: A string value representing the dashboard id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: array
description: JSON array with the list of customer ids, or empty to remove all customers
items:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Dashboard'
/api/dashboard/{dashboardId}/customers/remove:
post:
tags:
- dashboard-controller
summary: Remove the Dashboard Customers (removeDashboardCustomers)
description: 'Removes the list of Customers from the existing list of assignments for the Dashboard. Keeps other assignments to customers that are not in the provided list. Returns the Dashboard object.
Available for users with ''TENANT_ADMIN'' authority.'
operationId: removeDashboardCustomers
parameters:
- name: dashboardId
in: path
description: A string value representing the dashboard id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: array
description: JSON array with the list of customer ids
items:
type: string
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Dashboard'
/api/dashboard/{dashboardId}/customers/add:
post:
tags:
- dashboard-controller
summary: Adds the Dashboard Customers (addDashboardCustomers)
description: 'Adds the list of Customers to the existing list of assignments for the Dashboard. Keeps previous assignments to customers that are not in the provided list. Returns the Dashboard object.
Available for users with ''TENANT_ADMIN'' authority.'
operationId: addDashboardCustomers
parameters:
- name: dashboardId
in: path
description: A string value representing the dashboard id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: array
description: JSON array with the list of customer ids
items:
type: string
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Dashboard'
/api/customer/{customerId}/dashboard/{dashboardId}:
post:
tags:
- dashboard-controller
summary: Assign the Dashboard (assignDashboardToCustomer)
description: 'Assign the Dashboard to specified Customer or do nothing if the Dashboard is already assigned to that Customer. Returns the Dashboard object.
Available for users with ''TENANT_ADMIN'' authority.'
operationId: assignDashboardToCustomer
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: dashboardId
in: path
description: A string value representing the dashboard id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Dashboard'
delete:
tags:
- dashboard-controller
summary: Unassign the Dashboard (unassignDashboardFromCustomer)
description: 'Unassign the Dashboard from specified Customer or do nothing if the Dashboard is already assigned to that Customer. Returns the Dashboard object.
Available for users with ''TENANT_ADMIN'' authority.'
operationId: unassignDashboardFromCustomer
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: dashboardId
in: path
description: A string value representing the dashboard id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Dashboard'
/api/customer/public/dashboard/{dashboardId}:
post:
tags:
- dashboard-controller
summary: Assign the Dashboard to Public Customer (assignDashboardToPublicCustomer)
description: 'Assigns the dashboard to a special, auto-generated ''Public'' Customer. Once assigned, unauthenticated users may browse the dashboard. This method is useful if you like to embed the
dashboard on public web pages to be available for users that are not logged in. Be aware that making the dashboard public does not mean that it automatically makes all devices and assets you use
in the dashboard to be public.Use [assign Asset to Public Customer](#!/asset-controller/assignAssetToPublicCustomerUsingPOST) and [assign Device to Public Customer](#!/device-controller/assignDeviceToPublicCustomerUsingPOST)
for this purpose. Returns the Dashboard object.
Available for users with ''TENANT_ADMIN'' authority.'
operationId: assignDashboardToPublicCustomer
parameters:
- name: dashboardId
in: path
description: A string value representing the dashboard id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Dashboard'
delete:
tags:
- dashboard-controller
summary: Unassign the Dashboard from Public Customer (unassignDashboardFromPublicCustomer)
description: 'Unassigns the dashboard from a special, auto-generated ''Public'' Customer. Once unassigned, unauthenticated users may no longer browse the dashboard. Returns the Dashboard object.
Available for users with ''TENANT_ADMIN'' a
# --- truncated at 32 KB (118 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/thingsboard/refs/heads/main/openapi/thingsboard-dashboards-openapi.yml