Attributes
Publish Client-Side Attributes
Section titled “Publish Client-Side Attributes”Upload client-side attributes for one or more devices.
Topic: v1/gateway/attributes
{ "Device A": {"fw_version": "1.0.3", "battery": 87}, "Device B": {"fw_version": "2.1.0", "battery": 92}}Replace GATEWAY_DEVICE_ACCESS_TOKEN in the commands below with the gateway device’s access token.
mosquitto_pub -h "mqtt.thingsboard.cloud" -t "v1/gateway/attributes" -u "GATEWAY_DEVICE_ACCESS_TOKEN" -m '{"Device A":{"fw_version":"1.0.3","battery":87}}'Request Attribute Values
Section titled “Request Attribute Values”Subscribe to the response topic first, then publish the request.
Subscribe: v1/gateway/attributes/response
Publish: v1/gateway/attributes/request
Request:
| Field | Required | Description |
|---|---|---|
id |
Yes | Integer request identifier — echoed in the response |
device |
Yes | Name of a device connected through this gateway |
clientKeys |
No | Comma-separated client attribute keys to return; use "" (empty string) to return all client attributes; omit the field entirely to exclude the client scope |
sharedKeys |
No | Comma-separated shared attribute keys to return; use "" (empty string) to return all shared attributes; omit the field entirely to exclude the shared scope |
Omitting both clientKeys and sharedKeys (sending only id and device) returns all client and all shared attributes.
{"id": 1, "device": "Device A", "clientKeys": "fw_version,battery", "sharedKeys": "targetFwVersion"}Response:
{"id": 1, "device": "Device A", "client": {"fw_version": "1.0.3", "battery": 87}, "shared": {"targetFwVersion": "2.0.1"}}A scope appears in the response only if it returned at least one attribute, so it is absent both when you did not ask for it and when the device has nothing in it.
Example
Section titled “Example”The gateway keeps a single MQTT connection open per device, so use mosquitto_rr: it subscribes, publishes the request, and waits for the response over that one connection, matching the request/response pattern this API expects.
Replace GATEWAY_DEVICE_ACCESS_TOKEN in the commands below with the gateway device’s access token.
mosquitto_rr -d -q 1 -h "mqtt.thingsboard.cloud" -p 1883 -t "v1/gateway/attributes/request" -e "v1/gateway/attributes/response" -u "GATEWAY_DEVICE_ACCESS_TOKEN" -m '{"id":1,"device":"Device A","clientKeys":"fw_version,battery","sharedKeys":"targetFwVersion"}'Response:
{"id": 1, "device": "Device A", "client": {"fw_version": "1.0.3", "battery": 87}, "shared": {"targetFwVersion": "2.0.1"}}mosquitto_rr -d -q 1 -h "mqtt.thingsboard.cloud" -p 1883 -t "v1/gateway/attributes/request" -e "v1/gateway/attributes/response" -u "GATEWAY_DEVICE_ACCESS_TOKEN" -m '{"id":1,"device":"Device A","clientKeys":""}'Response:
{"id": 1, "device": "Device A", "client": {"fw_version": "1.0.3", "battery": 87}}mosquitto_rr -d -q 1 -h "mqtt.thingsboard.cloud" -p 1883 -t "v1/gateway/attributes/request" -e "v1/gateway/attributes/response" -u "GATEWAY_DEVICE_ACCESS_TOKEN" -m '{"id":1,"device":"Device A","sharedKeys":""}'Response:
{"id": 1, "device": "Device A", "shared": {"targetFwVersion": "2.0.1"}}mosquitto_rr -d -q 1 -h "mqtt.thingsboard.cloud" -p 1883 -t "v1/gateway/attributes/request" -e "v1/gateway/attributes/response" -u "GATEWAY_DEVICE_ACCESS_TOKEN" -m '{"id":1,"device":"Device A"}'Response:
{"id": 1, "device": "Device A", "client": {"fw_version": "1.0.3", "battery": 87}, "shared": {"targetFwVersion": "2.0.1"}}Deprecated request/response format
Section titled “Deprecated request/response format”| Field | Required | Description |
|---|---|---|
id |
Yes | Integer request identifier — echoed in the response |
device |
Yes | Name of a device connected through this gateway |
client |
Yes | Boolean flag: set to true to request client-side attributes, or false to request shared attributes |
key |
Yes* | A single attribute key to return |
keys |
Yes* | Array of attribute keys to return |
* Send either key or keys, not both — key takes precedence when both are present.
{"id": 1, "device": "Device A", "keys": ["fw_version", "battery"], "client": true}mosquitto_rr -d -q 1 -h "mqtt.thingsboard.cloud" -p 1883 -t "v1/gateway/attributes/request" -e "v1/gateway/attributes/response" -u "GATEWAY_DEVICE_ACCESS_TOKEN" -m '{"id":1,"device":"Device A","keys":["fw_version","battery"],"client":true}'client selects the scope for the keys you list, and the response returns value when that scope produced a single attribute or values when it produced several.
{"id": 1, "device": "Device A", "values": {"fw_version": "1.0.3", "battery": 87}}With key or keys set, a request returns a single scope — the one client selects. clientKeys/sharedKeys can return both scopes in one request, and all attributes of a scope without naming them.
Subscribe to Shared Attribute Updates
Section titled “Subscribe to Shared Attribute Updates”Subscribe to receive push notifications when shared attributes change for any downstream device.
Topic: v1/gateway/attributes (subscribe)
mosquitto_sub -h "mqtt.thingsboard.cloud" -t "v1/gateway/attributes" -u "$ACCESS_TOKEN"ThingsBoard delivers updates in this format:
{ "device": "Device A", "data": {"targetFwVersion": "2.0.1", "enabled": true}}Was this helpful?