Attributes
The CoAP Attributes API lets devices upload client-side attributes, request attribute values, and subscribe to shared attribute updates using the CoAP Observe option. For an explanation of attribute types, see Attributes.
See Getting Connected for credential types and connection details.
Publish Client-Side Attributes
Section titled “Publish Client-Side Attributes”Send a POST request to upload client-side attributes:
| Credential type | URL |
|---|---|
| Access Token | coap(s)://coap.thingsboard.cloud/api/v1/$ACCESS_TOKEN/attributes |
| X.509 Certificate | coaps://coap.thingsboard.cloud/api/v1/attributes |
{"attribute1": "value1", "attribute2": true, "attribute3": 42.0}Access Token:
coap-client -v 6 -m POST -t "application/json" -e '{"attribute1":"value1","attribute2":true,"attribute3":42.0}' "coap://coap.thingsboard.cloud:5683/api/v1/$ACCESS_TOKEN/attributes"X.509 Certificate:
coap-client-openssl -v 6 -c cert.pem -j key.pem -m POST -t "application/json" -e '{"attribute1":"value1","attribute2":true,"attribute3":42.0}' "coaps://coap.thingsboard.cloud/api/v1/attributes"Request Attribute Values
Section titled “Request Attribute Values”Send a GET request to the attributes endpoint to read client-side and/or shared attribute values. The response groups results by scope: {"client": {...}, "shared": {...}}.
Endpoint:
| Credential type | Endpoint |
|---|---|
| Access Token | coap(s)://coap.thingsboard.cloud/api/v1/$ACCESS_TOKEN/attributes |
| X.509 Certificate | coaps://coap.thingsboard.cloud/api/v1/attributes |
Query parameters — choose which attributes to return:
| Parameter | Description |
|---|---|
clientKeys |
Comma-separated list of client-side attribute keys to return |
sharedKeys |
Comma-separated list of shared attribute keys to return |
allClientKeys |
Set to true to return all client-side attributes (overrides clientKeys) |
allSharedKeys |
Set to true to return all shared attributes (overrides sharedKeys) |
Sending no query parameters at all returns all client-side and all shared attributes.
Example:
Access Token:
coap-client -v 6 -m GET "coap://coap.thingsboard.cloud:5683/api/v1/$ACCESS_TOKEN/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2"X.509 Certificate:
coap-client-openssl -v 6 -c cert.pem -j key.pem -m GET "coaps://coap.thingsboard.cloud/api/v1/attributes?clientKeys=attribute1,attribute2&sharedKeys=shared1,shared2"Response:
{"client": {"attribute1": "value1", "attribute2": true}, "shared": {"shared1": "value2", "shared2": false}}Access Token:
coap-client -v 6 -m GET "coap://coap.thingsboard.cloud:5683/api/v1/$ACCESS_TOKEN/attributes?allClientKeys=true"X.509 Certificate:
coap-client-openssl -v 6 -c cert.pem -j key.pem -m GET "coaps://coap.thingsboard.cloud/api/v1/attributes?allClientKeys=true"Response:
{"client": {"attribute1": "value1", "attribute2": true}}Access Token:
coap-client -v 6 -m GET "coap://coap.thingsboard.cloud:5683/api/v1/$ACCESS_TOKEN/attributes?allSharedKeys=true"X.509 Certificate:
coap-client-openssl -v 6 -c cert.pem -j key.pem -m GET "coaps://coap.thingsboard.cloud/api/v1/attributes?allSharedKeys=true"Response:
{"shared": {"shared1": "value2", "shared2": false}}Access Token:
coap-client -v 6 -m GET "coap://coap.thingsboard.cloud:5683/api/v1/$ACCESS_TOKEN/attributes?allClientKeys=true&allSharedKeys=true"X.509 Certificate:
coap-client-openssl -v 6 -c cert.pem -j key.pem -m GET "coaps://coap.thingsboard.cloud/api/v1/attributes?allClientKeys=true&allSharedKeys=true"Response:
{"client": {"attribute1": "value1", "attribute2": true}, "shared": {"shared1": "value2", "shared2": false}}The response includes a scope only if that scope returned at least one attribute. Ask for ?allClientKeys=true and the response has no shared object at all. The same happens to a scope you did ask for, if the device has no attributes in it.
When the device profile payload type is set to Protobuf, the request and response use fixed schemas. See MQTT Attributes for the Protobuf schemas.
Subscribe to Shared Attribute Updates
Section titled “Subscribe to Shared Attribute Updates”Use the CoAP Observe option to receive push notifications when shared attributes change. The connection stays open and ThingsBoard sends a response each time a shared attribute is updated.
| Credential type | URL |
|---|---|
| Access Token | coap(s)://coap.thingsboard.cloud/api/v1/$ACCESS_TOKEN/attributes/updates |
| X.509 Certificate | coaps://coap.thingsboard.cloud/api/v1/attributes/updates |
Access Token (observe for 60 seconds):
coap-client -v 6 -m GET -s 60 "coap://coap.thingsboard.cloud:5683/api/v1/$ACCESS_TOKEN/attributes/updates"X.509 Certificate:
coap-client-openssl -v 6 -c cert.pem -j key.pem -m GET -s 60 "coaps://coap.thingsboard.cloud/api/v1/attributes/updates"When a shared attribute changes, ThingsBoard pushes the updated values:
{"shared": {"firmware_version": "2.1.0"}}When the device profile payload type is set to Protobuf, notifications use a fixed schema. See MQTT Attributes for the Protobuf schema.
Was this helpful?