Thingsboard API reference

Device connectivity and server-side APIs.

HTTP Device API Reference

Getting started

HTTP basics

HTTP is a general-purpose network protocol that can be use 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 a HTTP Server that supports both HTTP and HTTPS protocols.

Client libraries setup

You can find HTTP client libraries for different programming languages in the web. Examples in this article will be based on curl. In order to setup this tool, you can use instructions in our Hello World guide.

HTTP Authentication and error codes

We will use access token device credentials in this article and they will be referred to later as $ACCESS_TOKEN. Application need to include $ACCESS_TOKEN as a path parameter into each HTTP request. Possible error codes and their reasons:

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 or long. Using custom binary format or some serialization framework is also possible. See protocol customization for more details. For example:

{"stringKey":"value1", "booleanKey":true, "doubleKey":42.0, "longKey":73}

Telemetry upload API

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

http(s)://host:port/api/v1/$ACCESS_TOKEN/telemetry

The simplest supported data formats are:

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

or

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

Please note that in this case, 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:

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

In the example above, we assume that “1451649600512” is a unix timestamp with milliseconds precision. For example, the value ‘1451649600512’ corresponds to ‘Fri, 01 Jan 2016 12:00:00.512 GMT’

resources/http-telemetry.sh
# Publish data as an object without timestamp (server-side timestamp will be used)
curl -v -X POST -d @telemetry-data-as-object.json http://localhost:8080/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"
# Publish data as an array of objects without timestamp (server-side timestamp will be used)
curl -v -X POST -d @telemetry-data-as-array.json http://localhost:8080/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"
# Publish data as an object with timestamp (server-side timestamp will be used)
curl -v -X POST -d @telemetry-data-with-ts.json http://localhost:8080/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"
resources/telemetry-data-as-object.json
{"key1":"value1", "key2":true, "key3": 3.0, "key4": 4}
resources/telemetry-data-as-array.json
[{"key1":"value1"}, {"key2":true}]
resources/telemetry-data-with-ts.json
{"ts":1451649600512, "values":{"key1":"value1", "key2":"value2"}}

Attributes API

Thingsboard attributes API allows devices to

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:

http(s)://host:port/api/v1/$ACCESS_TOKEN/attributes
resources/http-attributes-publish.sh
# Publish client-side attributes update
curl -v -X POST -d @new-attributes-values.json http://localhost:8080/api/v1/$ACCESS_TOKEN/attributes --header "Content-Type:application/json"
resources/new-attributes-values.json
{"attribute1":"value1", "attribute2":true, "attribute3":42.0, "attribute4":73}
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:

http(s)://host:port/api/v1/$ACCESS_TOKEN/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2
resources/http-attributes-request.sh
# Send HTTP attributes request
curl -v -X GET http://localhost:8080/api/v1/$ACCESS_TOKEN/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2

Please note, intersection of client-side and shared device attribute keys is a bad practise! 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:

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

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

resources/http-attributes-subscribe.sh
# Send subscribe attributes request with 20 seconds timeout
curl -v -X GET http://localhost:8080/api/v1/$ACCESS_TOKEN/attributes/updates?timeout=20000

RPC API

Server-side RPC

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

http(s)://host:port/api/v1/$ACCESS_TOKEN/rpc

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

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

where

and can reply to them using POST request to the following URL:

http://host:port/api/v1/$ACCESS_TOKEN/rpc/{$id}

where $id is an integer request identifier.

resources/http-rpc-subscribe.sh
# Send rpc request with 20 seconds timeout
curl -v -X GET http://localhost:8080/api/v1/$ACCESS_TOKEN/rpc?timeout=20000
resources/http-rpc-reply.sh
# Publish response to RPC request
curl -v -X POST -d @rpc-response.json http://localhost:8080/api/v1/$ACCESS_TOKEN/rpc/1 --header "Content-Type:application/json"
resources/rpc-response.json
{"result":"ok"}

Client-side RPC

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

http://host:port/api/v1/$ACCESS_TOKEN/rpc

Both request and response body should be a valid JSON documents. Content of the documents is specific to the plugin that will handle your request.

resources/http-rpc-from-client.sh
# Post client-side rpc request
curl -X POST -d @rpc-client-request.json http://localhost:8080/api/v1/$ACCESS_TOKEN/rpc --header "Content-Type:application/json"
resources/rpc-client-request.json
{"method": "getTime", "params":{}}
resources/rpc-server-response.json
{"time":"2016 11 21 12:54:44.287"}

Protocol customization

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