Entities

View Entities in the API reference

An entity is the controllable “thing” on a device—for example a specific relay channel, light, or sensor. Entities belong to devices and are placed in zones either through their device or directly.

Zone placement

Each entity has a zone object with one of three modes:

zone	Effective zone
{ "mode": "inherit" }	The device’s zone_id, or none when the device has no zone. Default.
{ "mode": "explicit", "zone_id": "01J…" }	That zone, whatever the device’s zone is.
{ "mode": "none" }	None, even when the device has a zone. Use it to keep an entity out of zone-scoped policies.

Create and update requests take zone in this shape. The bare zone_id field isn’t accepted on requests. These return 400:

• mode: "explicit" without zone_id
• zone_id with mode: "inherit" or mode: "none"
• a top-level zone_id field

An explicit zone_id must be a non-deleted zone in the entity’s org; otherwise the request returns 422.

Responses include the placement plus two read-only fields:

{
  "zone": { "mode": "inherit", "zone_id": null },
  "effective_zone_id": "01J8ZONEA…",
  "zone_source": "device"
}

zone_source is "entity" for an explicit placement, "device" when the zone comes from the device, "door" when a door that lists the entity as an opener or light owns the zone, and null when there’s no effective zone. For "door", zone_door_id names the door.

A door-listed entity has no zone of its own. Setting an explicit zone on it, or wiring an entity that has an explicit zone into a door, returns 409 with error_code: "door_zone_conflict". inherit and none are still accepted.

Example: a relay board’s device zone is Zone A. Seven of its relays inherit Zone A; relay 3 is explicit in Zone B. Moving the board to Zone C moves the seven inheriting relays and leaves relay 3 in Zone B.

Filtering by zone

GET /entities?zone_id={id} matches the effective zone. Add include_descendants=true to include entities in sub-zones. Both combine with q and sort. A malformed zone_id returns 400. Entities with mode: "none" never match.

See Resource hierarchy for the data model. For API endpoints (list, create, update, set state, delete), use the link above.