openapi: 3.1.0
info:
title: ThingsBoard Admin admin-controller device-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: device-controller
description: Device
paths:
/api/tenant/{tenantId}/device/{deviceId}:
post:
tags:
- device-controller
summary: Assign Device to Tenant (assignDeviceToTenant)
description: 'Creates assignment of the device to tenant. Thereafter tenant will be able to reassign the device to a customer.
Available for users with ''TENANT_ADMIN'' authority.'
operationId: assignDeviceToTenant
parameters:
- name: tenantId
in: path
description: A string value representing the tenant id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
- name: deviceId
in: path
description: A string value representing the device id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Device'
/api/edge/{edgeId}/device/{deviceId}:
post:
tags:
- device-controller
summary: Assign Device to Edge (assignDeviceToEdge)
description: 'Creates assignment of an existing device 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 device (Edge will receive this instantly, if it''s currently connected, or once it''s going to be connected to platform). Third, once device 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: assignDeviceToEdge
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: deviceId
in: path
description: A string value representing the device id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Device'
delete:
tags:
- device-controller
summary: Unassign Device from Edge (unassignDeviceFromEdge)
description: 'Clears assignment of the device 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 device (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 device locally.
Available for users with ''TENANT_ADMIN'' authority.'
operationId: unassignDeviceFromEdge
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: deviceId
in: path
description: A string value representing the device id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Device'
/api/devices:
get:
tags:
- device-controller
summary: Get Devices by Ids (getDevicesByIds)
description: "Requested devices must be owned by tenant or assigned to customer which user is performing the request. \n\nAvailable for users with 'TENANT_ADMIN' or 'CUSTOMER_USER' authority."
operationId: getDevicesByIds
parameters:
- name: deviceIds
in: query
description: A list of devices 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/Device'
post:
tags:
- device-controller
summary: Find Related Devices (findByQuery)
description: 'Returns all devices that are related to the specific entity. The entity id, relation type, device types, depth of the search, and other query parameters defined using complex ''DeviceSearchQuery'' object. See ''Model'' tab of the Parameters for more info.
Available for users with ''TENANT_ADMIN'' or ''CUSTOMER_USER'' authority.'
operationId: findByQuery_3
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DeviceSearchQuery'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Device'
/api/device:
post:
tags:
- device-controller
summary: Create or Update Device (saveDevice)
description: "Create or update the Device. When creating device, platform generates Device Id as [time-based UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_1_(date-time_and_MAC_address)). Device credentials are also generated if not provided in the 'accessToken' request parameter. The newly created device id will be present in the response. Specify existing Device id to update the device. Referencing non-existing device Id will cause 'Not Found' error.\n\nDevice name is unique in the scope of tenant. Use unique identifiers like MAC or IMEI for the device names and non-unique 'label' field for user-friendly visualization purposes.Remove 'id', 'tenantId' and optionally 'customerId' from the request body example (below) to create new Device entity. \n\nAvailable for users with 'TENANT_ADMIN' or 'CUSTOMER_USER' authority."
operationId: saveDevice
parameters:
- name: accessToken
in: query
description: Optional value of the device credentials to be used during device creation. If omitted, access token will be auto-generated.
required: false
schema:
type: string
- 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 device.
content:
application/json:
schema:
$ref: '#/components/schemas/Device'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Device'
/api/device/credentials:
post:
tags:
- device-controller
summary: Update Device Credentials (updateDeviceCredentials)
description: "During device creation, platform generates random 'ACCESS_TOKEN' credentials. \" +\nUse this method to update the device credentials. First use 'getDeviceCredentialsByDeviceId' to get the credentials id and value.\nThen use current method to update the credentials type and value. It is not possible to create multiple device credentials for the same device.\nThe structure of device credentials id and value is simple for the 'ACCESS_TOKEN' but is much more complex for the 'MQTT_BASIC' or 'LWM2M_CREDENTIALS'.\nYou may find the example of device with different type of credentials below: \n\n- Credentials type: <b>\"Access token\"</b> with <b>device ID</b> and with <b>device ID</b> below: \n\n```json\n{\n \"id\": {\n \"id\":\"c886a090-168d-11ee-87c9-6f157dbc816a\"\n },\n \"deviceId\": {\n \"id\":\"c5fb3ac0-168d-11ee-87c9-6f157dbc816a\",\n \"entityType\":\"DEVICE\"\n },\n \"credentialsType\": \"ACCESS_TOKEN\",\n \"credentialsId\": \"6hmxew8pmmzng4e3une4\"\n}\n```\n\n- Credentials type: <b>\"X509\"</b> with <b>device profile ID</b> below: \n\nNote: <b>credentialsId</b> - format <b>Sha3Hash</b>, <b>certificateValue</b> - format <b>PEM</b> (with \"--BEGIN CERTIFICATE----\" and -\"----END CERTIFICATE-\").\n\n```json\n{\n \"id\": {\n \"id\":\"309bd9c0-14f4-11ee-9fc9-d9b7463abb63\"\n },\n \"deviceId\": {\n \"id\":\"3092b200-14f4-11ee-9fc9-d9b7463abb63\",\n \"entityType\":\"DEVICE\"\n },\n \"credentialsType\": \"X509_CERTIFICATE\",\n \"credentialsId\": \"6b8adb49015500e51a527acd332b51684ab9b49b4ade03a9582a44c455e2e9b6\",\n \"credentialsValue\": \"-----BEGIN CERTIFICATE----- MIICMTCCAdegAwIBAgIUUEKxS9hTz4l+oLUMF0LV6TC/gCIwCgYIKoZIzj0EAwIwbjELMAkGA1UEBhMCVVMxETAPBgNVBAgMCE5ldyBZb3JrMRowGAYDVQQKDBFUaGluZ3NCb2FyZCwgSW5jLjEwMC4GA1UEAwwnZGV2aWNlUHJvZmlsZUNlcnRAWDUwOVByb3Zpc2lvblN0cmF0ZWd5MB4XDTIzMDMyOTE0NTczNloXDTI0MDMyODE0NTczNlowbjELMAkGA1UEBhMCVVMxETAPBgNVBAgMCE5ldyBZb3JrMRowGAYDVQQKDBFUaGluZ3NCb2FyZCwgSW5jLjEwMC4GA1UEAwwnZGV2aWNlUHJvZmlsZUNlcnRAWDUwOVByb3Zpc2lvblN0cmF0ZWd5MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAECMlWO72krDoUL9FQjUmSCetkhaEGJUfQkdSfkLSNa0GyAEIMbfmzI4zITeapunu4rGet3EMyLydQzuQanBicp6NTMFEwHQYDVR0OBBYEFHpZ78tPnztNii4Da/yCw6mhEIL3MB8GA1UdIwQYMBaAFHpZ78tPnztNii4Da/yCw6mhEIL3MA8GA1UdEwEB/wQFMAMBAf8wCgYIKoZIzj0EAwIDSAAwRQIgJ7qyMFqNcwSYkH6o+UlQXzLWfwZbNjVk+aR7foAZNGsCIQDsd7v3WQIGHiArfZeDs1DLEDuV/2h6L+ZNoGNhEKL+1A== -----END CERTIFICATE-----\"\n}\n```\n\n- Credentials type: <b>\"MQTT_BASIC\"</b> with <b>device profile ID</b> below: \n\n```json\n{\n \"id\": {\n \"id\":\"d877ffb0-14f5-11ee-9fc9-d9b7463abb63\"\n },\n \"deviceId\": {\n \"id\":\"d875dcd0-14f5-11ee-9fc9-d9b7463abb63\",\n \"entityType\":\"DEVICE\"\n },\n \"credentialsType\": \"MQTT_BASIC\",\n \"credentialsValue\": \"{\\\"clientId\\\":\\\"juy03yv4owqxcmqhqtvk\\\",\\\"userName\\\":\\\"ov19fxca0cyjn7lm7w7u\\\",\\\"password\\\":\\\"twy94he114dfi9usyk1o\\\"}\"\n}\n```\n\n- You may find the example of <b>LwM2M</b> device and <b>RPK</b> credentials below: \n\nNote: LwM2M device - only existing device profile ID (Transport configuration -> Transport type: \"LWM2M\".\n\n```json\n{\n \"id\": {\n \"id\":\"e238d4d0-1689-11ee-98c6-1713c1be5a8e\"\n },\n \"deviceId\": {\n \"id\":\"e232e160-1689-11ee-98c6-1713c1be5a8e\",\n \"entityType\":\"DEVICE\"\n },\n \"credentialsType\": \"LWM2M_CREDENTIALS\",\n \"credentialsId\": \"LwRpk00000000\",\n \"credentialsValue\":\n \"{\\\"client\\\":{ \\\"endpoint\\\":\\\"LwRpk00000000\\\", \\\"securityConfigClientMode\\\":\\\"RPK\\\", \\\"key\\\":\\\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEdvBZZ2vQRK9wgDhctj6B1c7bxR3Z0wYg1+YdoYFnVUKWb+rIfTTyYK9tmQJx5Vlb5fxdLnVv1RJOPiwsLIQbAA==\\\" }, \\\"bootstrap\\\":{ \\\"bootstrapServer\\\":{ \\\"securityMode\\\":\\\"RPK\\\", \\\"clientPublicKeyOrId\\\":\\\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEUEBxNl/RcYJNm8mk91CyVXoIJiROYDlXcSSqK6e5bDHwOW4ZiN2lNnXalyF0Jxw8MbAytnDMERXyAja5VEMeVQ==\\\", \\\"clientSecretKey\\\":\\\"MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgd9GAx7yZW37autew5KZykn4IgRpge/tZSjnudnZJnMahRANCAARQQHE2X9Fxgk2byaT3ULJVeggmJE5gOVdxJKorp7lsMfA5bhmI3aU2ddqXIXQnHDwxsDK2cMwRFfICNrlUQx5V\\\"}, \\\"lwm2mServer\\\":{ \\\"securityMode\\\":\\\"RPK\\\", \\\"clientPublicKeyOrId\\\":\\\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEUEBxNl/RcYJNm8mk91CyVXoIJiROYDlXcSSqK6e5bDHwOW4ZiN2lNnXalyF0Jxw8MbAytnDMERXyAja5VEMeVQ==\\\", \\\"clientSecretKey\\\":\\\"MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgd9GAx7yZW37autew5KZykn4IgRpge/tZSjnudnZJnMahRANCAARQQHE2X9Fxgk2byaT3ULJVeggmJE5gOVdxJKorp7lsMfA5bhmI3aU2ddqXIXQnHDwxsDK2cMwRFfICNrlUQx5V\\\"}} }\"\n}\n```\n\nUpdate to real value:\n - 'id' (this is id of Device Credentials -> \"Get Device Credentials (getDeviceCredentialsByDeviceId)\",\n - 'deviceId.id' (this is id of Device).\nRemove 'tenantId' and optionally 'customerId' from the request body example (below) to create new Device entity.\n\nAvailable for users with 'TENANT_ADMIN' authority."
operationId: updateDeviceCredentials
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DeviceCredentials'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DeviceCredentials'
/api/device/bulk_import:
post:
tags:
- device-controller
summary: Import the Bulk of Devices (processDevicesBulkImport)
description: 'There''s an ability to import the bulk of devices using the only .csv file.
Available for users with ''TENANT_ADMIN'' authority.'
operationId: processDevicesBulkImport
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BulkImportRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BulkImportResultDevice'
/api/device-with-credentials:
post:
tags:
- device-controller
summary: Create Device (saveDevice) with Credentials
description: "Create or update the Device. When creating device, platform generates Device Id as [time-based UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_1_(date-time_and_MAC_address)). Requires to provide the Device Credentials object as well as an existing device profile ID or use \"default\".\nYou may find the example of device with different type of credentials below: \n\n- Credentials type: <b>\"Access token\"</b> with <b>device profile ID</b> below: \n\n```json\n{\n \"device\": {\n \"name\":\"Name_DeviceWithCredantial_AccessToken\",\n \"label\":\"Label_DeviceWithCredantial_AccessToken\",\n \"deviceProfileId\":{\n \"id\":\"9d9588c0-06c9-11ee-b618-19be30fdeb60\",\n \"entityType\":\"DEVICE_PROFILE\"\n }\n },\n \"credentials\": {\n \"credentialsType\": \"ACCESS_TOKEN\",\n \"credentialsId\": \"6hmxew8pmmzng4e3une2\"\n }\n}\n```\n\n- Credentials type: <b>\"Access token\"</b> with <b>device profile default</b> below: \n\n```json\n{\n \"device\": {\n \"name\":\"Name_DeviceWithCredantial_AccessToken_Default\",\n \"label\":\"Label_DeviceWithCredantial_AccessToken_Default\",\n \"type\": \"default\"\n },\n \"credentials\": {\n \"credentialsType\": \"ACCESS_TOKEN\",\n \"credentialsId\": \"6hmxew8pmmzng4e3une3\"\n }\n}\n```\n\n- Credentials type: <b>\"X509\"</b> with <b>device profile ID</b> below: \n\nNote: <b>credentialsId</b> - format <b>Sha3Hash</b>, <b>certificateValue</b> - format <b>PEM</b> (with \"--BEGIN CERTIFICATE----\" and -\"----END CERTIFICATE-\").\n\n```json\n{\n \"device\": {\n \"name\":\"Name_DeviceWithCredantial_X509_Certificate\",\n \"label\":\"Label_DeviceWithCredantial_X509_Certificate\",\n \"deviceProfileId\":{\n \"id\":\"9d9588c0-06c9-11ee-b618-19be30fdeb60\",\n \"entityType\":\"DEVICE_PROFILE\"\n }\n },\n \"credentials\": {\n \"credentialsType\": \"X509_CERTIFICATE\",\n \"credentialsId\": \"84f5911765abba1f96bf4165604e9e90338fc6214081a8e623b6ff9669aedb27\",\n \"credentialsValue\": \"-----BEGIN CERTIFICATE----- MIICMTCCAdegAwIBAgIUI9dBuwN6pTtK6uZ03rkiCwV4wEYwCgYIKoZIzj0EAwIwbjELMAkGA1UEBhMCVVMxETAPBgNVBAgMCE5ldyBZb3JrMRowGAYDVQQKDBFUaGluZ3NCb2FyZCwgSW5jLjEwMC4GA1UEAwwnZGV2aWNlQ2VydGlmaWNhdGVAWDUwOVByb3Zpc2lvblN0cmF0ZWd5MB4XDTIzMDMyOTE0NTYxN1oXDTI0MDMyODE0NTYxN1owbjELMAkGA1UEBhMCVVMxETAPBgNVBAgMCE5ldyBZb3JrMRowGAYDVQQKDBFUaGluZ3NCb2FyZCwgSW5jLjEwMC4GA1UEAwwnZGV2aWNlQ2VydGlmaWNhdGVAWDUwOVByb3Zpc2lvblN0cmF0ZWd5MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE9Zo791qKQiGNBm11r4ZGxh+w+ossZL3xc46ufq5QckQHP7zkD2XDAcmP5GvdkM1sBFN9AWaCkQfNnWmfERsOOKNTMFEwHQYDVR0OBBYEFFFc5uyCyglQoZiKhzXzMcQ3BKORMB8GA1UdIwQYMBaAFFFc5uyCyglQoZiKhzXzMcQ3BKORMA8GA1UdEwEB/wQFMAMBAf8wCgYIKoZIzj0EAwIDSAAwRQIhANbA9CuhoOifZMMmqkpuld+65CR+ItKdXeRAhLMZuccuAiB0FSQB34zMutXrZj1g8Gl5OkE7YryFHbei1z0SveHR8g== -----END CERTIFICATE-----\"\n }\n}\n```\n\n- Credentials type: <b>\"MQTT_BASIC\"</b> with <b>device profile ID</b> below: \n\n```json\n{\n \"device\": {\n \"name\":\"Name_DeviceWithCredantial_MQTT_Basic\",\n \"label\":\"Label_DeviceWithCredantial_MQTT_Basic\",\n \"deviceProfileId\":{\n \"id\":\"9d9588c0-06c9-11ee-b618-19be30fdeb60\",\n \"entityType\":\"DEVICE_PROFILE\"\n }\n },\n \"credentials\": {\n \"credentialsType\": \"MQTT_BASIC\",\n \"credentialsValue\": \"{\\\"clientId\\\":\\\"5euh5nzm34bjjh1efmlt\\\",\\\"userName\\\":\\\"onasd1lgwasmjl7v2v7h\\\",\\\"password\\\":\\\"b9xtm4ny8kt9zewaga5o\\\"}\"\n }\n}\n```\n\n- You may find the example of <b>LwM2M</b> device and <b>RPK</b> credentials below: \n\nNote: LwM2M device - only existing device profile ID (Transport configuration -> Transport type: \"LWM2M\".\n\n```json\n{\n \"device\": {\n \"name\":\"Name_LwRpk00000000\",\n \"label\":\"Label_LwRpk00000000\",\n \"deviceProfileId\":{\n \"id\":\"a660bd50-10ef-11ee-8737-b5634e73c779\",\n \"entityType\":\"DEVICE_PROFILE\"\n }\n },\n \"credentials\": {\n \"credentialsType\": \"LWM2M_CREDENTIALS\",\n \"credentialsId\": \"LwRpk00000000\",\n \"credentialsValue\":\n \"{\\\"client\\\":{ \\\"endpoint\\\":\\\"LwRpk00000000\\\", \\\"securityConfigClientMode\\\":\\\"RPK\\\", \\\"key\\\":\\\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEUEBxNl/RcYJNm8mk91CyVXoIJiROYDlXcSSqK6e5bDHwOW4ZiN2lNnXalyF0Jxw8MbAytnDMERXyAja5VEMeVQ==\\\" }, \\\"bootstrap\\\":{ \\\"bootstrapServer\\\":{ \\\"securityMode\\\":\\\"RPK\\\", \\\"clientPublicKeyOrId\\\":\\\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEUEBxNl/RcYJNm8mk91CyVXoIJiROYDlXcSSqK6e5bDHwOW4ZiN2lNnXalyF0Jxw8MbAytnDMERXyAja5VEMeVQ==\\\", \\\"clientSecretKey\\\":\\\"MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgd9GAx7yZW37autew5KZykn4IgRpge/tZSjnudnZJnMahRANCAARQQHE2X9Fxgk2byaT3ULJVeggmJE5gOVdxJKorp7lsMfA5bhmI3aU2ddqXIXQnHDwxsDK2cMwRFfICNrlUQx5V\\\"}, \\\"lwm2mServer\\\":{ \\\"securityMode\\\":\\\"RPK\\\", \\\"clientPublicKeyOrId\\\":\\\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEUEBxNl/RcYJNm8mk91CyVXoIJiROYDlXcSSqK6e5bDHwOW4ZiN2lNnXalyF0Jxw8MbAytnDMERXyAja5VEMeVQ==\\\", \\\"clientSecretKey\\\":\\\"MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgd9GAx7yZW37autew5KZykn4IgRpge/tZSjnudnZJnMahRANCAARQQHE2X9Fxgk2byaT3ULJVeggmJE5gOVdxJKorp7lsMfA5bhmI3aU2ddqXIXQnHDwxsDK2cMwRFfICNrlUQx5V\\\"}} }\"\n }\n}\n```\n\nRemove 'id', 'tenantId' and optionally 'customerId' from the request body example (below) to create new Device entity. \n\nAvailable for users with 'TENANT_ADMIN' or 'CUSTOMER_USER' authority."
operationId: saveDeviceWithCredentials_1
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/SaveDeviceWithCredentialsRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Device'
/api/customer/{customerId}/device/{deviceId}:
post:
tags:
- device-controller
summary: Assign Device to Customer (assignDeviceToCustomer)
description: 'Creates assignment of the device to customer. Customer will be able to query device afterwards.
Available for users with ''TENANT_ADMIN'' authority.'
operationId: assignDeviceToCustomer
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: deviceId
in: path
description: A string value representing the device id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Device'
/api/customer/public/device/{deviceId}:
post:
tags:
- device-controller
summary: Make Device Publicly Available (assignDeviceToPublicCustomer)
description: 'Device 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 device.
Available for users with ''TENANT_ADMIN'' authority.'
operationId: assignDeviceToPublicCustomer
parameters:
- name: deviceId
in: path
description: A string value representing the device id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Device'
/api/customer/device/{deviceName}/claim:
post:
tags:
- device-controller
summary: Claim Device (claimDevice)
description: "Claiming makes it possible to assign a device to the specific customer using device/server side claiming data (in the form of secret key).To make this happen you have to provide unique device name and optional claiming data (it is needed only for device-side claiming).Once device is claimed, the customer becomes its owner and customer users may access device data as well as control the device. \nIn order to enable claiming devices feature a system parameter security.claim.allowClaimingByDefault should be set to true, otherwise a server-side claimingAllowed attribute with the value true is obligatory for provisioned devices. \nSee official documentation for more details regarding claiming.\n\nAvailable for users with 'CUSTOMER_USER' authority."
operationId: claimDevice
parameters:
- name: deviceName
in: path
description: Unique name of the device which is going to be claimed
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ClaimRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
type: string
delete:
tags:
- device-controller
summary: Reclaim Device (reClaimDevice)
description: 'Reclaiming means the device will be unassigned from the customer and the device will be available for claiming again.
Available for users with ''TENANT_ADMIN'' or ''CUSTOMER_USER'' authority.'
operationId: reClaimDevice
parameters:
- name: deviceName
in: path
description: Unique name of the device which is going to be reclaimed
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
type: string
/api/tenant/devices:
get:
tags:
- device-controller
summary: Get Tenant Device (getTenantDevice)
description: 'Requested device must be owned by tenant that the user belongs to. Device name is an unique property of device. So it can be used to identify the device.
Available for users with ''TENANT_ADMIN'' authority.'
operationId: getTenantDevices
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: Device type as the name of the device profile
required: false
schema:
type: string
- name: textSearch
in: query
description: The case insensitive 'substring' filter based on the device 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
- deviceProfileName
- label
- customerTitle
- name: sortOrder
in: query
description: Sort order. ASC (ASCENDING) or DESC (DESCENDING)
required: false
schema:
type: string
enum:
- ASC
- DESC
- name: deviceName
in: query
description: A string value representing the Device name.
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Device'
- $ref: '#/components/schemas/PageDataDevice'
/api/tenant/deviceInfos:
get:
tags:
- device-controller
summary: Get Tenant Device Infos (getTenantDeviceInfos)
description: "Returns a page of devices 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. Device Info is an extension of the default Device object that contains information about the assigned customer name and device profile name. \n\nAvailable for users with 'TENANT_ADMIN' authority."
operationId: getTenantDeviceInfos
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: Device type as the name of the device profile
required: false
schema:
type: string
- name: deviceProfileId
in: query
description: A string value representing the device profile id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: false
schema:
type: string
- name: active
in: query
description: A boolean value representing the device active flag.
required: false
schema:
type: boolean
- name: textSearch
in: query
description: The case insensitive 'substring' filter based on the device 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
- deviceProfileName
- 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/PageDataDeviceInfo'
/api/edge/{edgeId}/devices:
get:
tags:
- device-controller
summary: Get Devices Assigned to Edge (getEdgeDevices)
description: "Returns a page of devices 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. \n\nAvailable for users with 'TENANT_ADMIN' or 'CUSTOMER_USER' authority."
operationId: getEdgeDevices
parameters:
- name: edgeId
in: path
description: A string value representing the edge id. For example, '784f394
# --- truncated at 32 KB (67 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/thingsboard/refs/heads/main/openapi/thingsboard-device-controller-api-openapi.yml