Pricing Try it now
Edge
Community Edition Professional Edition Cloud Edge PE Edge IoT Gateway License Server Trendz Analytics Mobile Application PE Mobile Application MQTT Broker PE MQTT Broker
API > Device Connectivity APIs > HTTP Device API
Getting Started Documentation Installation Architecture
FAQ
On this page

HTTP Device API Reference

HTTP is a general-purpose network protocol that can be used in IoT applications. You can find more information about HTTP here. HTTP protocol is TCP based and uses request-response model.

ThingsBoard server nodes act as an HTTP Server that supports both HTTP and HTTPS protocols.

Client libraries setup

Many HTTP client libraries are available for different platforms and languages. The examples in this article will be based on curl.

Install curl for Linux

1

sudo apt-get install curl

Starting with Windows 10 build 17063 and macOS 10.2 6C115 (Jaguar), cURL is available by default.

HTTP authentication method

ThingsBoard supports access token-based authentication to secure HTTP connections. For each HTTP request, the client must include the access token as part of the request URL.

The examples in this guide use access token–based authentication.

Possible error codes and their reasons:

  • 400 Bad Request - Invalid URL, request parameters or body
  • 401 Unauthorized - Invalid access token
  • 404 Not Found - Requested resource does not exist

Key-value format

By default, ThingsBoard supports key-value content in JSON. Key is always a string, while value can be either string, boolean, double, long or JSON. For example:

1
2
3
4
5
6
7
8
9
10
11

{
 "stringKey":"value1", 
 "booleanKey":true, 
 "doubleKey":42.0, 
 "longKey":73, 
 "jsonKey": {
    "someNumber": 42,
    "someArray": [1,2,3],
    "someNestedObject": {"key": "value"}
 }
}

Using custom binary format or some serialization framework is also possible. See protocol customization for more details.

Telemetry upload API

In order to publish telemetry data to ThingsBoard server node, send POST request to the following URL:

1

http(s)://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/telemetry

⚠️ Where
 • $THINGSBOARD_EDGE_HOST_NAME is your ThingsBoard Edge hostname or IP address.
 • $ACCESS_TOKEN is the device's access token.

The simplest supported data formats are:

1

{"key1":"value1", "key2":"value2"}

or

1

[{"key1":"value1"}, {"key2":"value2"}]

In this case, the server-side timestamp will be assigned to uploaded data!

In case your device is able to get the client-side timestamp, you can use following format:

1

{"ts":1451649600512, "values":{"key1":"value1", "key2":"value2"}}

Where 1451649600512 is a unix timestamp with milliseconds precision. For example, the value ‘1451649600512’ corresponds to ‘Fri, 01 Jan 2016 12:00:00.512 GMT’


Below are the examples of commands for publishing different types of telemetry data.

⚠️ Don't forget to replace
 • $THINGSBOARD_EDGE_HOST_NAME is your ThingsBoard Edge hostname or IP address.
 • $ACCESS_TOKEN is your device's access token.

Example 1.
Publish data as an object without timestamp (server-side timestamp will be used).

Execute the command:

1

curl -v -X POST --data "{"temperature":42,"humidity":73}" http://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"

Telemetry data:

1

{"temperature":42,"humidity":73}

Example 2.
Publish data as an object without timestamp (server-side timestamp will be used) using data from telemetry-data-as-object.json file.

Execute the command:

1

curl -v -X POST -d @telemetry-data-as-object.json http://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"

The content of the JSON file:

1
2
3
4
5
6
7
8
9
10
11

{
  "stringKey": "value1",
  "booleanKey": true,
  "doubleKey": 42.0,
  "longKey": 73,
  "jsonKey": {
    "someNumber": 42,
    "someArray": [1,2,3],
    "someNestedObject": {"key": "value"}
  }
}

Example 3.
Publish data as an array of objects without timestamp (server-side timestamp will be used) using data from telemetry-data-as-array.json file.

Execute the command:

1

curl -v -X POST -d @telemetry-data-as-array.json http://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"

The content of the JSON file:

1

[{"key1":"value1"}, {"key2":true}]

Example 4. Publish data as an object with timestamp (telemetry timestamp will be used) using data from telemetry-data-with-ts.json file.

Execute the command:

1

curl -v -X POST -d @telemetry-data-with-ts.json http://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"

The content of the JSON file:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

{
  "ts": 1451649600512,
  "values": {
    "stringKey": "value1",
    "booleanKey": true,
    "doubleKey": 42.0,
    "longKey": 73,
    "jsonKey": {
      "someNumber": 42,
      "someArray": [1, 2, 3],
      "someNestedObject": {
        "key": "value"
      }
    }
  }
}

Attributes API

ThingsBoard attributes API allows devices to

  • Upload client-side device attributes to the server.
  • Request client-side and shared device attributes from the server.
  • Subscribe to shared device attributes from the server.

Publish attribute update to the server

In order to publish client-side device attributes to ThingsBoard server node, send POST request to the following URL:

1

http(s)://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/attributes

Where
 • $THINGSBOARD_EDGE_HOST_NAME is your ThingsBoard Edge hostname or IP address.
 • $ACCESS_TOKEN is the device's access token.

Below are the examples of commands for publishing different types of telemetry data.

Example 1.
Publish client-side attributes update

1

curl -v -X POST --data "{"attribute1": "value1", "attribute2":true, "attribute3": 43.0}" http://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/attributes --header "Content-Type:application/json"

Example 2.
Publish client-side attributes update from the new-attributes-values.json file.

1

curl -v -X POST -d @new-attributes-values.json http://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/attributes --header "Content-Type:application/json"

The content of the JSON file:

1
2
3
4
5
6
7
8
9
10
11

{
  "attribute1": "value1",
  "attribute2": true,
  "attribute3": 42.0,
  "attribute4": 73,
  "attribute5": {
    "someNumber": 42,
    "someArray": [1,2,3],
    "someNestedObject": {"key": "value"}
  }
}

Request attribute values from the server

In order to request client-side or shared device attributes to ThingsBoard server node, send GET request to the following URL:

1

http(s)://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2

Where
 • $THINGSBOARD_EDGE_HOST_NAME is your ThingsBoard Edge hostname or IP address.
 • $ACCESS_TOKEN is the device's access token.


1

curl -v -X GET http://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2

Result:

1

{"client":{"attribute1":"value1","attribute2":true}}
Doc info icon

Please note
the intersection of client-side and shared device attribute keys is a bad practice! However, it is still possible to have same keys for client, shared or even server-side attributes.

Subscribe to attribute updates from the server

In order to subscribe to shared device attribute changes, send GET request with optional “timeout” request parameter to the following URL:

1

http(s)://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/attributes/updates

Where
 • $THINGSBOARD_EDGE_HOST_NAME is your ThingsBoard Edge hostname or IP address.
 • $ACCESS_TOKEN is the device's access token.

Once shared attribute will be changed by one of the server-side components (REST API or Rule Chain) the client will receive the following update:

1

curl -v -X GET http://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/attributes/updates?timeout=20000

Result:

1

{"client":{"attribute1":"value1","attribute2":true}}

JSON value support

We have added support of JSON data structures to telemetry and attributes API to simplify work with device configuration. JSON support allows you to both upload from the device, and push nested objects to the device. You can store one configuration JSON as a shared attribute and push it to the device. You can also process the JSON data in the rule engine and raise alarms, etc.

Therefore, this improvement minimizes the number of Database operations when ThingsBoard stores the data. For example, “temperature” and “humidity” would be stored as separate rows in SQL or NoSQL databases in order to efficiently aggregate this data for visualization. Since there is no need to aggregate JSON data, we can store all the content as one row instead of separate rows for each configuration item. In some of our environments, it is possible to decrease the number of database operations more than 10 times by aggregating multiple parameters within one JSON.

Learn more about JSON value support with the video.

RPC API

Server-side RPC

In order to subscribe to RPC commands from the server, send GET request with optional “timeout” request parameter to the following URL:

1

http(s)://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/rpc

Where
 • $THINGSBOARD_EDGE_HOST_NAME is your ThingsBoard Edge hostname or IP address.
 • $ACCESS_TOKEN is the device's access token.

Once subscribed, a client may receive rpc request or a timeout message if there are no requests to a particular device. An example of RPC request body is shown below:

1
2
3
4
5
6
7
8

{
  "id": "1",
  "method": "setGpio",
  "params": {
    "pin": "23",
    "value": 1
  }
}

Where
 • id - request id, integer request identifier
 • method - RPC method name, string
 • params - RPC method params, custom json object

It is possible to reply to them using POST request to the following URL:

1

http(s)://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/rpc/{$id}

Where $id is an integer request identifier.


Let's look at an example:

  • Use RPC debug terminal widget in your ThingsBoard instance;
  • Subscribe to RPC commands from the server using the command below. To do this, in the first terminal window send GET request with observe flag.
1

curl -v -X GET http://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/rpc?timeout=20000

Where
 • $THINGSBOARD_EDGE_HOST_NAME is your ThingsBoard Edge hostname or IP address.
 • $ACCESS_TOKEN is the device's access token.

  • Send an RPC request “connect” to the device using RPC debug terminal widget;
  • Save the rpc-response.json file to your PC;
  • In the second terminal window simulate sending a response from the device to the server:
1

curl -v -X POST -d @rpc-response.json http://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/rpc/1 --header "Content-Type:application/json"

You should receive a response from the device:

1

{"result":"ok"}

Client-side RPC

In order to send RPC commands to the server, send POST request to the following URL:

1

http(s)://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/rpc

Where
 • $THINGSBOARD_EDGE_HOST_NAME is your ThingsBoard Edge hostname or IP address.
 • $ACCESS_TOKEN is the device's access token.

Both request and response body should be valid JSON documents. The content of the documents is specific to the rule node that will handle your request.


Example

1

return {msg: {time: new Date()}, metadata: metadata, msgType: msgType};

1

curl -X POST -d @rpc-client-request.json http://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/rpc --header "Content-Type:application/json"

You should receive a response from the server:

1

{"time":"Thursday, February 5, 2026, 9:08:22 AM Coordinated Universal Time"}

Claiming devices

The Device Claiming feature allows end users to securely associate a device with their account after the device has been deployed and connected to ThingsBoard. For a detailed explanation of the device claiming workflow and supported scenarios, refer to the Claiming devices documentation.

Claiming request
To initiate the device claiming process, the device must send a POST request to the following endpoint:

1

http(s)://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/claim

Where
 • $THINGSBOARD_EDGE_HOST_NAME is your ThingsBoard Edge hostname or IP address.
 • $ACCESS_TOKEN is the device's access token.

Request payload
The request body must contain the following JSON structure:

1

{"secretKey":"value", "durationMs":60000}

Payload fields

  • secretKey — a secret value used to authorize the claiming process
  • durationMs — the time window (in milliseconds) during which the device can be claimed
Doc info icon

Please note that the above fields are optional. In case the secretKey is not specified, the empty string as a default value is used. In case the durationMs is not specified, the system parameter device.claim.duration is used (in the file /etc/thingsboard/conf/thingsboard.yml).

Device provisioning

Device provisioning allows devices to be registered dynamically without manual creation in the ThingsBoard UI. For a detailed explanation of the provisioning process and supported scenarios, refer to the Device provisioning documentation.

Provisioning request To initiate device provisioning, send a POST request to the following endpoint:

1

http(s)://$THINGSBOARD_EDGE_HOST_NAME/api/v1/provision

Where $THINGSBOARD_EDGE_HOST_NAME is your ThingsBoard Edge hostname or IP address.

Request Payload
The provisioning request must use the following JSON format:

1
2
3
4
5

{
  "deviceName": "DEVICE_NAME",
  "provisionDeviceKey": "u7piawkboq8v32dmcmpp",
  "provisionDeviceSecret": "jpmwdn8ptlswmf4m29bw"
}

Payload fields

  • deviceName — the name of the device to be provisioned.
  • provisionDeviceKey — the provisioning key configured in ThingsBoard.
  • provisionDeviceSecret — the provisioning secret associated with the provisioning key.

If the provided credentials are valid, ThingsBoard automatically creates the device (if it does not already exist) and returns the device credentials, allowing the device to start communicating with the platform.

Firmware API

When ThingsBoard initiates the firmware update over HTTP it sets the fw_title, fw_version, fw_checksum, fw_checksum_algorithm shared attributes.

To receive firmware update information and download the firmware, the device must send a GET request to the following endpoint:

1

http(s)://$THINGSBOARD_EDGE_HOST_NAME/api/v1/$ACCESS_TOKEN/firmware?title=$TITLE&version=$VERSION

Parameters
 • $THINGSBOARD_EDGE_HOST_NAME is your ThingsBoard Edge hostname or IP address
 • $ACCESS_TOKEN is your device's access token
 • $TITLE - the firmware title
 • $VERSION - the target firmware version

Protocol customization

HTTP transport can be fully customized for specific use-case by changing the corresponding module.

Next steps