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, and $THINGSBOARD_HOST with your ThingsBoard instance’s host.

mosquitto_pub -h "$THINGSBOARD_HOST" -t "v1/gateway/attributes" -u "GATEWAY_DEVICE_ACCESS_TOKEN" -m '{"Device A":{"fw_version":"1.0.3","battery":87}}'

Subscribe to the response topic first, then publish the request.

Subscribe: v1/gateway/attributes/response

Publish: v1/gateway/attributes/request

Request:

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.

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, and $THINGSBOARD_HOST with your ThingsBoard instance’s host.

mosquitto_rr -d -q 1 -h "$THINGSBOARD_HOST" -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"}'

{"id": 1, "device": "Device A", "client": {"fw_version": "1.0.3", "battery": 87}, "shared": {"targetFwVersion": "2.0.1"}}

mosquitto_rr -d -q 1 -h "$THINGSBOARD_HOST" -p 1883 -t "v1/gateway/attributes/request" -e "v1/gateway/attributes/response" -u "GATEWAY_DEVICE_ACCESS_TOKEN" -m '{"id":1,"device":"Device A","clientKeys":""}'

{"id": 1, "device": "Device A", "client": {"fw_version": "1.0.3", "battery": 87}}

mosquitto_rr -d -q 1 -h "$THINGSBOARD_HOST" -p 1883 -t "v1/gateway/attributes/request" -e "v1/gateway/attributes/response" -u "GATEWAY_DEVICE_ACCESS_TOKEN" -m '{"id":1,"device":"Device A","sharedKeys":""}'

{"id": 1, "device": "Device A", "shared": {"targetFwVersion": "2.0.1"}}

mosquitto_rr -d -q 1 -h "$THINGSBOARD_HOST" -p 1883 -t "v1/gateway/attributes/request" -e "v1/gateway/attributes/response" -u "GATEWAY_DEVICE_ACCESS_TOKEN" -m '{"id":1,"device":"Device A"}'

{"id": 1, "device": "Device A", "client": {"fw_version": "1.0.3", "battery": 87}, "shared": {"targetFwVersion": "2.0.1"}}

* 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 "$THINGSBOARD_HOST" -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 receive push notifications when shared attributes change for any downstream device.

Topic: v1/gateway/attributes (subscribe)

mosquitto_sub -h "$THINGSBOARD_HOST" -t "v1/gateway/attributes" -u "$ACCESS_TOKEN"

ThingsBoard delivers updates in this format:

{
  "device": "Device A",
  "data": {"targetFwVersion": "2.0.1", "enabled": true}
}