Skip to content

Managing Attributes

This guide covers how to create, update, and delete device attributes using the Qbee web UI and REST API.

Permissions

  • Viewing attributes requires the device:read permission.
  • Updating attributes requires the device:manage permission.

See Account, Users, and Roles for details on permission management.

Managing via web UI

Creating a custom attribute

  1. Navigate to Devices and select the target device.
  2. On the device overview page, locate the Attributes widget.
  3. Click Edit.
  4. In the edit dialog, enter a Key (max 64 characters) and a Value (max 4096 characters) in the input fields at the bottom.
  5. Click Add.
  6. Click Save to persist the changes.

The dialog displays a counter (e.g., 3/10) showing how many custom attributes are in use versus the maximum allowed.

Editing a custom attribute

  1. Click Edit on the Attributes widget.
  2. Modify the Value field of any existing attribute. Keys cannot be changed after creation.
  3. Click Save.

Deleting a custom attribute

  1. Click Edit on the Attributes widget.
  2. Click the delete button next to the attribute you want to remove.
  3. The row is marked for deletion. You can click undo to restore it before saving.
  4. Click Save to confirm the deletion.

Reading attributes via API

Retrieve the current attributes for a device using a GET request:

curl -s \
  -H "Authorization: Bearer ${QBEE_API_TOKEN}" \
  "https://www.app.qbee.io/api/v2/deviceattribute/${DEVICE_ID}"

Example response:

{
  "device_name": "gateway-01",
  "description": "Edge gateway in warehouse B",
  "latitude": "52.5200",
  "longitude": "13.4050",
  "country": "DE",
  "city": "Berlin",
  "zip": "10115",
  "address": "Unter den Linden 1",
  "custom": {
    "env": "production",
    "rack": "A3",
    "serial": "SN-98765"
  }
}

Setting custom attributes via API

Update custom attributes with a PATCH request. Only the attributes you include in the request body are modified — existing attributes not mentioned remain unchanged.

curl -s -X PATCH \
  -H "Authorization: Bearer ${QBEE_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "custom": {
      "env": "staging",
      "region": "eu-west"
    }
  }' \
  "https://www.app.qbee.io/api/v2/deviceattribute/${DEVICE_ID}"

This sets env to "staging" and adds region with value "eu-west". Any other existing custom attributes remain untouched.

Setting legacy attributes via API

Update legacy attributes (device name, description, location) in the same PATCH request:

curl -s -X PATCH \
  -H "Authorization: Bearer ${QBEE_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "device_name": "gateway-01",
    "description": "Edge gateway in warehouse B",
    "latitude": "52.5200",
    "longitude": "13.4050",
    "country": "DE",
    "city": "Berlin"
  }' \
  "https://www.app.qbee.io/api/v2/deviceattribute/${DEVICE_ID}"

You can combine legacy and custom attributes in a single request:

curl -s -X PATCH \
  -H "Authorization: Bearer ${QBEE_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "device_name": "gateway-01",
    "custom": {
      "env": "production"
    }
  }' \
  "https://www.app.qbee.io/api/v2/deviceattribute/${DEVICE_ID}"

Coordinate validation

latitude must be a valid latitude value (-90 to 90) and longitude must be a valid longitude value (-180 to 180). Invalid coordinates are rejected with an error.

Deleting attributes via API

To delete a custom attribute, send a PATCH request with an empty string as its value:

curl -s -X PATCH \
  -H "Authorization: Bearer ${QBEE_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "custom": {
      "env": ""
    }
  }' \
  "https://www.app.qbee.io/api/v2/deviceattribute/${DEVICE_ID}"

This removes the env attribute from the device. Other custom attributes remain unaffected.

The same empty-string convention works for legacy attributes. Setting "description": "" clears the description field.

What Next?

I want to... Go to
Read and set attributes from the device using qbee-agent Device-Side Access
Filter my fleet by attribute values Searching by Attributes
Learn more about the REST API REST API