Send a field the device type does not define

Add your own keys to a reading. They are stored and shown, but they never drive an alert or a forecast.

A device type declares a fixed set of fields. A custom key is any other field you add to the same data object.

When to use a custom key#

Use a custom key when you have a value the device type does not declare. An example is a vibration reading on a device type with no vibration field. Logable stores the value and can display it. It cannot use the value for anything else.

Rules#

A custom key must start with a letter. After that it may hold letters, digits or underscores, up to 64 characters in total.

Custom key limits
Limit	Value	Description
custom keys	20	Maximum number of custom (unregistered) keys in one payload.
key length	64	Maximum characters in a custom key.
string value length	256	Maximum characters in a custom key's string value.

What happens to the value#

A custom value appears on the device's Metrics tab and can be plotted on a chart. It cannot be used inside a rule condition. It is never read by a forecast.

What is rejected#

A key that breaks the naming rule, a value of the wrong type, or a string over the length limit is rejected. So is a payload with more than 20 custom keys, with the message Too many custom data keys ({n}); max is 20. Every one of these failures returns HTTP 400 with code: "VALIDATION_ERROR".

Example#

Custom data point

{
  "data": {
    "weight": 18750.5,
    "status": "filling",
    "vibration_rms": 0.42
  }
}

weight and status are fields the device type declares. vibration_rms is the custom key.