Device catalog

After OAuth client credentials authentication, a control device can retrieve its command and sensor catalog through the HTTPS iot/v1 catalog endpoints by providing the returned Bearer access token.

Normal firmware startup should use GET /iot/v1/devices/{device_id}/bootstrap, which includes the same command and sensor catalogs together with runtime metadata. The endpoints on this page remain valid for targeted granular catalog reads.

Command data describes the actuator state configured through the control panel. Sensor data describes the expected sensor inputs that the device can report through feed-data ingestion.

Catalog payloads are the firmware contract. Devices should use the technical fields present in each payload, such as id, kind, value_type, qc, mu, and pin_port, for routing and reporting; resource/dashboard row labels and sensor descriptions are UI metadata in Realer.

These command endpoints are catalog-only. They are not a command queue and do not return pending desired states. HTTPS devices read pending desired states from GET /iot/v1/devices/{device_id}/desired-states; MQTT devices receive desired-state messages on their runtime topics.

On this page

Commands

cURL 
curl "https://api.therealer.com/iot/v1/devices/cdv_aaaaaaaaaaaaaaaaaaaaaaaaaa/commands" \
  -H 'Authorization: Bearer b11db7f6c816568eb3b156df3aeaa5'
GET /iot/v1/devices/{device_id}/commands

Retrieve all commands registered for the authenticated control device.

Request headers
Authorization
(required)

The Bearer access token obtained from the OAuth token endpoint.

Type: String

Example: Bearer b11db7f6c816568eb3b156df3aeaa5

Path parameters
device_id
(required)

Public id of the authenticated control device.

Type: String

Example: cdv_aaaaaaaaaaaaaaaaaaaaaaaaaa

Responses

200 OK

JSON 
{
  "code": 2000,
  "commands": [
    {
      "id": "cmd_bbbbbbbbbbbbbbbbbbbbbbbbbb",
      "value": "0.0",
      "value_type": "NumericRange",
      "kind": "relay",
      "pin_port": "6"
    }
  ]
}

Schema: http-command-catalog-response.schema.json

GET /iot/v1/devices/{device_id}/commands/{id}

Retrieve one command. The response keeps the same array-based commands payload shape as the collection endpoint.

Sensors

cURL 
curl "https://api.therealer.com/iot/v1/devices/cdv_aaaaaaaaaaaaaaaaaaaaaaaaaa/sensors" \
  -H 'Authorization: Bearer b11db7f6c816568eb3b156df3aeaa5'
GET /iot/v1/devices/{device_id}/sensors

Retrieve all sensors registered for the authenticated control device.

Request headers
Authorization
(required)

The Bearer access token obtained from the OAuth token endpoint.

Type: String

Example: Bearer b11db7f6c816568eb3b156df3aeaa5

Path parameters
device_id
(required)

Public id of the authenticated control device.

Type: String

Example: cdv_aaaaaaaaaaaaaaaaaaaaaaaaaa

Responses

200 OK

JSON 
{
  "code": 2000,
  "sensors": [
    {
      "id": "sen_bbbbbbbbbbbbbbbbbbbbbbbbbb",
      "kind": "thermistor",
      "qc": "celsius_temperature",
      "mu": "degree_celsius:0",
      "pin_port": "5",
      "expected_update_interval_seconds": 60,
      "minimum_supported_update_interval_seconds": 30
    }
  ]
}

Schema: http-sensor-catalog-response.schema.json

GET /iot/v1/devices/{device_id}/sensors/{id}

Retrieve one sensor. The response keeps the same array-based sensors payload shape as the collection endpoint.

Firmware rules

  • Read catalog data after authentication and after reconnecting from a long offline interval.
  • Use catalog id values as stable command and sensor identifiers in feed-data requests.
  • Use catalog command values as the last configured command state. Use HTTPS desired-state polling or MQTT desired-state messages for actionable command requests from Realer.
  • Report physical command outcomes and sensor readings through feed-data ingestion.
  • For sensors, minimum_supported_update_interval_seconds is the fastest cadence supported by the purchased HTTPS plan. expected_update_interval_seconds is nullable and becomes non-null only when the developer configured an expected cadence; do not report faster than the minimum plan cadence.
  • If a stored command or sensor cannot be represented by the current device contract, the item keeps its id and exposes error instead of normal fields.