IGH developershome API v1 · 1.1.0

Resources

The house

GET /v1/house answers the home as the integration shows it: Floors → Rooms → units, plus rooms on no floor, units in no room and the scenes. Each unit and gang carries its id, name, class, kind, model, room, floor, operations and its current state (live). A module carries no state of its own; its gangs do.

Call GET /v1/house first and keep the ids: every other call takes them. Something not exposed is simply absent, and asking for it is 404 not_found.

Controlling devices

POST /v1/devices/{id}/control { op, args } (POST /v1/devices/{id}/control) runs one operation. op must be one of the device's operations from GET /v1/house; args depends on it (Control):

Operation Args
set_power { "on": true }
set_brightness { "bri": 0–100 }
set_position { "pos": 0–100 } (shutters, curtains)
open, close, stop none
set_mode { "mode": "auto" | "eco" | "manual" } (the unit's mode; sleep is not available)
set_temp, set_ac_mode, set_fan { "temp": 24 }, { "mode": "cool" }, { "fan": "auto" }
key { "key": "<remote key>" } (IR remotes)
run none (a scene; also POST /v1/scenes/{id}/run, POST /v1/scenes/{id}/run)

Scenes

Deleting a scene is done in the app.

Sensors, energy and activity

Automations and schedules

With automations: on the integration sees the automations whose every referenced unit, gang and scene is exposed (GET /v1/automations), and may create (POST /v1/automations) and edit (PATCH /v1/automations/{id}) them. With schedules: on the same goes for the gateway's schedules (GET /v1/schedules, POST /v1/schedules, PATCH /v1/schedules/{id}). Bodies use the app's own schema (Object).

Renaming rooms and units

With structural: on (offered only when the integration exposes everything or a floor or room), PATCH /v1/rooms/{id} { name } (PATCH /v1/rooms/{id}) and PATCH /v1/devices/{id} { name } (PATCH /v1/devices/{id}) rename a room or a unit or gang inside the exposure.

Creating, moving or deleting rooms, floors and units, renaming the room or floor that is itself the exposure's boundary, and any other field are 403 structural_not_allowed with appAction: rooms (rooms): tell the user to do it in the app.

Examples

Dim the kitchen light to 40%.

POST /v1/devices/8F3K2M9Q4T7W:5b0e6c1a-2f4d-4c3b-9a8e-7d6f5e4c3b2a:u-kitchen-light/control

{
  "op": "set_brightness",
  "args": {
    "bri": 40
  }
}

Answer 200:

{
  "house": "Cohen Home",
  "device": "8F3K2M9Q4T7W:5b0e6c1a-2f4d-4c3b-9a8e-7d6f5e4c3b2a:u-kitchen-light",
  "state": {
    "on": true,
    "bri": 40
  }
}

Close the kitchen shutter.

POST /v1/devices/8F3K2M9Q4T7W:5b0e6c1a-2f4d-4c3b-9a8e-7d6f5e4c3b2a:u-kitchen-module:1/control

{
  "op": "close"
}

Answer 200:

{
  "house": "Cohen Home",
  "device": "8F3K2M9Q4T7W:5b0e6c1a-2f4d-4c3b-9a8e-7d6f5e4c3b2a:u-kitchen-module:1",
  "state": {
    "pos": 0
  }
}

Run the Evening scene.

POST /v1/scenes/8F3K2M9Q4T7W:5b0e6c1a-2f4d-4c3b-9a8e-7d6f5e4c3b2a:scene:s-evening/run

Answer 200:

{
  "house": "Cohen Home",
  "device": "8F3K2M9Q4T7W:5b0e6c1a-2f4d-4c3b-9a8e-7d6f5e4c3b2a:scene:s-evening",
  "run": {
    "runId": "r-1"
  }
}

Open the front gate (the integration doesn't allow unlocking).

POST /v1/devices/8F3K2M9Q4T7W:5b0e6c1a-2f4d-4c3b-9a8e-7d6f5e4c3b2a:u-gate/control

{
  "op": "open"
}

Answer 403:

{
  "error": {
    "code": "unlock_not_allowed",
    "message": "Unlocking and opening are off for this API integration.",
    "appAction": "integrations.record"
  }
}

Put the kitchen light in eco mode.

POST /v1/devices/8F3K2M9Q4T7W:5b0e6c1a-2f4d-4c3b-9a8e-7d6f5e4c3b2a:u-kitchen-light/control

{
  "op": "set_mode",
  "args": {
    "mode": "eco"
  }
}

Answer 200:

{
  "house": "Cohen Home",
  "device": "8F3K2M9Q4T7W:5b0e6c1a-2f4d-4c3b-9a8e-7d6f5e4c3b2a:u-kitchen-light",
  "state": {
    "on": true,
    "bri": 40,
    "mode": "eco"
  }
}

What is in my home?

GET /v1/house

Answer 200:

{
  "house": "Cohen Home",
  "gateway": "8F3K2M9Q4T7W",
  "floors": [
    {
      "id": "f-ground",
      "name": "Ground floor",
      "rooms": [
        {
          "id": "r-kitchen",
          "name": "Kitchen",
          "floor": "f-ground",
          "units": [
            {
              "id": "8F3K2M9Q4T7W:5b0e6c1a-2f4d-4c3b-9a8e-7d6f5e4c3b2a:u-kitchen-light",
              "name": "Kitchen light",
              "class": "light_dimmer",
              "kind": "unit",
              "model": "IGHH",
              "room": "r-kitchen",
              "floor": "f-ground",
              "operations": [
                "set_power",
                "set_brightness",
                "set_mode"
              ],
              "state": {
                "on": true,
                "bri": 70
              }
            },
            {
              "id": "8F3K2M9Q4T7W:5b0e6c1a-2f4d-4c3b-9a8e-7d6f5e4c3b2a:u-kitchen-module",
              "name": "Kitchen wall",
              "class": "gang_module",
              "kind": "module",
              "model": "IGHHX2",
              "room": "r-kitchen",
              "floor": "f-ground",
              "operations": [],
              "gangs": [
                {
                  "id": "8F3K2M9Q4T7W:5b0e6c1a-2f4d-4c3b-9a8e-7d6f5e4c3b2a:u-kitchen-module:0",
                  "name": "Counter",
                  "gang": 0,
                  "room": "r-kitchen",
                  "floor": "f-ground",
                  "operations": [
                    "set_power"
                  ],
                  "state": {
                    "on": false
                  }
                },
                {
                  "id": "8F3K2M9Q4T7W:5b0e6c1a-2f4d-4c3b-9a8e-7d6f5e4c3b2a:u-kitchen-module:1",
                  "name": "Shutter",
                  "gang": 1,
                  "room": "r-kitchen",
                  "floor": "f-ground",
                  "operations": [
                    "set_position",
                    "open",
                    "close",
                    "stop"
                  ],
                  "state": {
                    "pos": 100
                  }
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "rooms": [],
  "units": [],
  "scenes": [
    {
      "id": "8F3K2M9Q4T7W:5b0e6c1a-2f4d-4c3b-9a8e-7d6f5e4c3b2a:scene:s-evening",
      "name": "Evening",
      "room": null,
      "floor": null
    }
  ]
}

Rename the Kitchen to Family kitchen.

PATCH /v1/rooms/r-kitchen

{
  "name": "Family kitchen"
}

Answer 200:

{
  "house": "Cohen Home",
  "room": {
    "id": "r-kitchen",
    "name": "Family kitchen"
  }
}

Change the Arrive home automation (someone changed it meanwhile).

PATCH /v1/automations/a-arrive

{
  "ifRevision": 3,
  "enabled": false
}

Answer 409:

{
  "error": {
    "code": "revision_mismatch",
    "message": "It changed since you read it: read it again."
  }
}

What happened to the kitchen light today?

GET /v1/activity?device=8F3K2M9Q4T7W%3A5b0e6c1a-2f4d-4c3b-9a8e-7d6f5e4c3b2a%3Au-kitchen-light&from=1760745600000&limit=20

Answer 200:

{
  "house": "Cohen Home",
  "entries": [],
  "nextTo": null
}

IGH home API 1.1.0. Generated from the doc source; do not edit.