Skip to content

REST API — devices

The device methods let you retrieve a list of objects and read the state of a selected object. One module may expose several objects, such as separate outputs. Start with the list, select an object, copy its object_id, and use it for the next read.

First configure access using Getting started. In the examples, replace SERVER_ADDRESS, PORT, and API_KEY with the installation address, HTTPS port, and key from the panel. Identifiers are fictional; use the values returned by your server in your integration. Method paths are relative to /integrations/api.

Common status fields

Responses use JSON, a text data format. The list is an array in [] brackets, while a single object's status is an object in {} braces. In both methods, status objects contain:

Field Meaning
object_id A text identifier for a specific object, copied exactly from the list.
device_type The object type, which helps identify the meaning of its fields.
attached A boolean indicating the object's availability as reported by the system. It does not confirm that all its values are valid.
logic_action In these reads it is "initial_device_status", identifying a response containing the object's state. It does not establish a subscription.

Other metadata, such as a description, module name, channel number, or module identifiers, depends on the object. It need not appear in every status. Functional field names and units also depend on the type; the examples below do not constitute a complete response schema.

Retrieve the list: GET /device/list

Retrieves an array of device status objects. Requires no parameters and no body, meaning the data part of a request.

HTTP request with an authorization header, meaning additional information included in the request:

GET /integrations/api/device/list HTTP/1.1
Host: SERVER_ADDRESS:PORT
Authorization: Bearer API_KEY

The same request using curl; --include also displays response headers:

curl --include --request GET \
  'https://SERVER_ADDRESS:PORT/integrations/api/device/list' \
  --header 'Authorization: Bearer API_KEY'

With HTTP 200, the body is an array of statuses. Each element is an object like the fragments shown below, with additional fields depending on the object. Do not assume a fixed element order.

Example response with a complete JSON body when there are no objects available in the list:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[]

An empty array with HTTP 200 is a valid result without a status field. It does not mean an error or a device's off state. When the list is empty, there is no identifier for a subsequent read; check the objects available in the installation.

Access errors (401, 403), the HTTPS redirect (308), and processing errors (500, including after the response wait times out) are described on the Responses and errors page.

Select an object and its identifier

  1. Find the intended object in the returned array using device_type and any available description, module name, or channel number.
  2. Copy that element's entire object_id and store it exactly as received, preserving case and every character.
  3. Pass this identifier to GET /device/status, then read the value together with attached and any validity flag.

Treat object_id as an opaque identifier: do not reconstruct it from device_id, level, and index. A module can have multiple objects, and this triple of numbers is not a universal unique key.

Read one object: GET /device/status

Retrieves a single status object. Requires one non-empty text query parameter, object_id. A query parameter is a value appended to the address after ?. No body is required.

The following example assumes that the list returned the fictional object_id value example-relay-A for the selected output. Replace it with the identifier copied exactly from your own list.

GET /integrations/api/device/status?object_id=example-relay-A HTTP/1.1
Host: SERVER_ADDRESS:PORT
Authorization: Bearer API_KEY

The same request using curl. The --get option sends a read request, while --data-urlencode encodes the parameter value for use in the URL, preserving the supplied identifier:

curl --include --get \
  'https://SERVER_ADDRESS:PORT/integrations/api/device/status' \
  --data-urlencode 'object_id=example-relay-A' \
  --header 'Authorization: Bearer API_KEY'

With HTTP 200, the body contains one JSON object, without an array around the status. The first of the three fragments below shows example response fields for this output. The read may already differ from the earlier list because the state may have changed.

Three response fragments and their interpretation

Each example is a response fragment, showing only selected fields. Such an object may be a list element or the result of reading one object; additional fields may appear. The choice of examples does not limit the types returned by the server.

Fragment 1 — relay output: io32_output

{
  "logic_action": "initial_device_status",
  "object_id": "example-relay-A",
  "device_type": "io32_output",
  "attached": true,
  "binary_output": false,
  "binary_output_valid": false
}

binary_output is a boolean. In this example, binary_output_valid=false means there is no valid read; the neutral binary_output=false does not confirm an off state. Only when binary_output_valid=true can false be interpreted as a reported off state and true as an on state. attached=true alone does not replace the validity flag.

Fragment 2 — temperature sensor: s4t_temperature_sensor

{
  "logic_action": "initial_device_status",
  "object_id": "example-temperature-B",
  "device_type": "s4t_temperature_sensor",
  "attached": true,
  "temperature": null
}

temperature is a number in °C, such as 21.5, or null when no measurement is known. The shown null does not mean 0 °C, despite the object's availability. This type does not return a separate validity flag for this measurement.

Fragment 3 — dimmer: l4_dimmer

{
  "logic_action": "initial_device_status",
  "object_id": "example-dimmer-C",
  "device_type": "l4_dimmer",
  "attached": true,
  "brightness": 60
}

brightness is an integer from 0 to 100, representing the brightness control percentage. In this example it is 60%. There is no separate validity flag for this field.

Errors when reading one object

A missing object_id, empty text, whitespace only, or a value other than one text parameter returns HTTP 400 with this complete JSON body:

{"error":"Device ID is required"}

An unknown identifier returns HTTP 404. Example with a complete JSON body:

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{"error":"Device not found"}

Retrieve the list again and copy the selected object's identifier. 404 is not the same as a status with attached=false: an unavailable object may still be listed and have a status. Common access errors (401, 403), the redirect (308), and processing errors (500) are described on the Responses and errors page.

Availability and subsequent reads

Evaluate each value together with object availability and a *_valid flag, if that type returns one. The names and presence of these flags vary between types. attached=true does not guarantee that every measurement or setting is valid, and null representing an unknown value is not zero.

Some fields may disappear after an object disconnects. A missing field is not a new zero reading or confirmation of an earlier stored value. Data retained by the integration from a previous response does not thereby become a current, confirmed reading.

Each request retrieves state. To refresh the data, make another request. These methods do not provide an event stream, REST subscriptions, webhooks, or SSE. The list is returned as one array, without pagination parameters or an order guarantee. No guaranteed polling frequency has been established.

The public REST API does not provide a device write method. The presence of metadata about write capabilities in a status does not establish such a method either. For control, use variables connected to project logic or scenes.

Return to Getting started to choose another task.