describeThings

The "describeThings" action describes specified things. You can specify things by ID or "thingName". You can also control the information returned about each thing.
 

Request examples

Minimal - describe by IDs

{
 "action": "describeThings",
 "params": {
   "ids": [ 1, "2" ]
 },
 "authToken": "replaceWithAuthTokenFromCreateSession" 
}
 
 

Minimal - describe by thing names

{
 "action": "describeThings",
 "params": {
   "thingNames": [ "My Device", "Changed Name" ],
   "includeMetrics": true
 },
 "authToken": "replaceWithAuthTokenFromCreateSession" 
}
 
 

 

Response examples

Minimal

{
 "authToken": "replaceWithAuthTokenFromCreateSession",
 "result": {
   "things": [
     {
       "id": 1,
       "thingName": "My Device",
       "status": "active",
       "createdTimestamp": "2025-08-28T10:47:13.041",
       "updatedTimestamp": "2025-08-28T10:47:13.041",
       "inactiveTimestamp": null,
       "manufacturer": "unknown",
       "model": "unknown",
       "thingType": "unknown",
       "serialNumber": "unknown",
       "purpose": "unknown",
       "location": "unknown",
       "lifecycleLabels": [],
       "hostnames": [],
       "description": "",
       "photo": null,
       "binaryFormat": "hex",
       "metadata": {}
     },
     {
       "id": 2,
       "thingName": "Changed Name",
       "status": "inactive",
       "createdTimestamp": "2025-08-28T10:47:13.041",
       "updatedTimestamp": "2025-08-28T10:47:13.041",
       "inactiveTimestamp": "2025-08-28T10:47:13.041",
       "manufacturer": "AllenBradley",
       "model": "ACME-123",
       "serialNumber": "AB678",
       "thingType": "ACME Temperature Sensor",
       "purpose": "Stamper temperature",
       "location": "factory1/line1/station1",
       "lifecycleLabels": ["out-of-warranty", "deprecated"],
       "hostnames": [ "127.0.0.1" ],
       "description": "The ACME Temperature Sensor gathers temperature data from the ACME stamper.",
       "metadata": { "myProperty": "myValue" },
       "photo": "ffd8ffee002141646f62650064400000000103001003020306",
       "binaryFormat": "hex"
     }
   ]
 },
 "errorCode": 0,
 "errorMessage": ""
}
 
 

 

Properties

Request properties ("params")

Property Description Default Type Limits (inclusive)

ids

An “id” is a unique identifier automatically generated by the server. In JSON, you may use an integer number or a string containing an integer number. The server automatically generates the "id" when you create an object such as a label or thing and stores it in the table as an integer. You cannot alter the "id" value. If your application needs to specify a specific numeric identifier for a label, use the "enum" property. You can use the "id" or "thingName" properties to identify and look up a thing.

 

 Automatically generated by the server array of integers Each array item is an integer from 0 to 2147483647

includeMetrics

The "includeMetrics" property includes dynamically calculated properties in the results when set to true.

 

By default, dynamically calculated properties are not included in the results because they take extra time to retrieve.

 Optional with default of false Boolean

true

false

thingNames

 The "thingNames" property specifies one or more thing names. Each item in the array is the exact name of a thing. You can use it to describe or delete things. Required - No default value array one or more thing name strings

 

Response properties ("result")

Property Description Type Limits (inclusive)

binaryFormat

 The "binaryFormat" property designates the format of binary values embedded in JSON strings. For more details, see "binaryFormat".  string One of the following: "base64", "hex", or "byteArray".

createdTimestamp

 The "createdTimestamp" property is the date and time when something, such as a thing or key, was originally created in ISO 8601 format, such as "2025-08-28T10:47:13.041". It is never null. timestamp An ISO 8601 timestamp

description

The "description" property provides additional information about an object, such as a label or thing. You can use it as internal or external documentation of a label's meaning, purpose, and usage.

Markdown is a good language for formatting description text. You must ensure the text is compatible with a JSON string. For example, you must escape a double quote character using the backslash character:  \".

 

In the Thing API, It defaults to "unknown" and is a string from 1 to 512 bytes. You cannot use it for lookups and filtering.

 string 1 to 65,500 bytes

hostnames

The "hostnames" property specifies zero or more hostnames assigned to the device. Each item in the array should be a different hostname. The API allows the same hostname to be assigned to many things.

 

When you use the "alterThing" action, omit the "hostnames" property to leave host names unchanged or specify a complete set of hostnames. The action does not allow you to change one hostname at a time.

 

The Thing API implements the "hostnames" property using the Label API. 

  • The API stores and manages hostnames in the label group, "faircom/hostnames".
  • An API client can retrieve a list of all hostnames by using the "listLabels" action with "partialGroupFilter": "faircom/hostnames".
  • An API client should use the Thing API's "hostnames" property to manage the host names assigned to a thing. It should not use the Label API to rename, link, or unlink host names to things.
 array of strings zero or more hostname strings of 1 to 64 bytes

id

The "id" property is the unique identifier of an object such as a label or thing. In JSON, you may use an integer number or a string containing an integer number. The server automatically generates the "id" when you create a label and stores it in the label table as an integer. You cannot alter the "id" value. If your application needs to specify a specific numeric identifier for a label, use the "enum" property.

 integer 0 to 9223372036854770000 in the Thing API 

inactiveTimestamp

 The "inactiveTimestamp" property is the date and time when the thing was last made inactive. It is null when the thing is active. It is returned in ISO 8601 format, such as "2025-08-28T10:47:13.041". timestamp ISO 8601 timestamp

lifecycleLabels

 The "lifecycleLabels" property assigns zero or more lifecycle labels to a thing. You can use it for fast lookups and filtering. array of strings "archived"
"acquired"
"deprecated"
"decommissioned"
"disposed"
"end-of-life"
"out-of-warranty"
"operational"
"testing"
"unknown"

location

The "location" property specifies the item's location. A thing may have one location. 

 

This API uses the Label API to manage manufacturers.

  • It uses the label group, "faircom/edge/location". 
  • An API client can use the "listLabels" action to retrieve the location list. 
  • An API client can use the "alterLabel" action to rename a location label.
  • An API client can use the "createLabel" action to create a location label.
  • An API client can use the "changeLabel" action to delete a location label, but the API client must first use the "listThings" action with the "locationFilter" property to ensure the label is unused.
 string 1 to 64 bytes

manufacturer

The "manufacturer" property specifies the manufacturer of the thing. A thing may have one manufacturer. Many things can share the same manufacturer. You can use it to do exact lookups and filtering.

 

This API uses the Label API to manage manufacturers.

  • It uses the label group, "faircom/thing/manufacturer". 
  • An API client can use the "listLabels" action to retrieve the manufacturer list. 
  • An API client can use the "alterLabel" action to rename a manufacturer label.
  • An API client can use the "createLabel" action to create a manufacturer label.
  • An API client can use the "changeLabel" action to delete a manufacturer label, but the API client must first use the "listThings" action with the "manufacturerFilter" property to ensure the label is unused.
 string 1 to 64 bytes

metadata

The "metadata" field allows a customer to add a JSON value to an object such as a label or thing. It is typically a JSON object, but may be any JSON value. Its purpose is to provide additional metadata about the label, such as translations in multiple languages, historical value changes, etc. The "alterLabel" action can only replace this value with a new JSON value.

 JSON 0 to 65,500 bytes

model

The"model" property specifies a thing's model. A thing may have one model. Many things can share the same model number. 

 

This API uses the Label API to manage models.

  • It uses the label group, "faircom/thing/model". 
  • An API client can use the "listLabels" action to retrieve the model list. 
  • An API client can use the "alterLabel" action to rename a model label.
  • An API client can use the "createLabel" action to create a model label.
  • An API client can use the "changeLabel" action to delete a model label, but the API client must first use the "listThings" action with the "modelFilter" property to ensure the label is unused.
 string 1 to 64 bytes

photo

 The "photo" property contains a photo of a thing. You cannot use it for lookups and filtering. string up to 2 GB

purpose

The "purpose" property provides a short description of the specified server's purpose.

 

In the Thing API, the "purpose" property specifies the thing's purpose, which is a short description of why a thing is in use. A thing may have one purpose. 

 

This API uses the Label API to manage purposes.

  • It uses the label group, "faircom/edge/purpose". 
  • An API client can use the "listLabels" action to retrieve the purpose list. 
  • An API client can use the "alterLabel" action to rename a purpose label.
  • An API client can use the "createLabel" action to create a purpose label.
  • An API client can use the "changeLabel" action to delete a purpose label, but the API client must first use the "listThings" action with the "purposeFilter" property to ensure the label is unused.
 string 1 to 64 bytes

serialNumber

 The "serialNumber" property specifies a thing's serial number. Typically a serial number uniquely identifies a thing, but things from different manufacturers may have the same serial numbers.  You can use it to do partial lookups and filtering. string 1 to 64 bytes

status

The "status" property defaults to "active". The alternative is "inactive", which indicates an item is no longer in active use. Setting an item to "status": "inactive", functions similarly to deleting an item without making the deletion permanent.

 

When the "status" property is omitted or set to null, API actions set the "status" property to "active". Thus, when you create an item, it defaults to being active. When you list items, the action defaults to returning active items.

 

To create, alter, and list inactive items, set the "status" property to "inactive".
Use a delete action to permanently delete an item.

 string enum

"active"

"inactive"

thingName

 The "thingName" property specifies the unique name of a thing.   string 1 to 64 bytes

thingType

The "thingType" property specifies the thing's type, which is a generic description of what the thing is, such as "plc". A thing may have one type. 

 

This API uses the Label API to manage types.

  • It uses the label group, "faircom/thing/type". 
  • An API client can use the "listLabels" action to retrieve the type list. 
  • An API client can use the "alterLabel" action to rename a type label.
  • An API client can use the "createLabel" action to create a type label.
  • An API client can use the "changeLabel" action to delete a type label, but the API client must first use the "listThings" action with the "thingTypeFilter" property to ensure the label is unused.
 string 1 to 64 bytes

updatedTimestamp

 The "updatedTimestamp" property is the date and time when the thing was last updated. It is the same as the "createdTimestamp" property when the thing has never been updated. It is returned in ISO 8601 format, such as "2025-08-28T10:47:13.041". timestamp ISO 8601 timestamp

 

 

Was this article helpful?

Give feedback about this article

Related Articles