General Notes
The Istabai API enables you to interact with your devices and heating settings programmatically via HTTP requests.
Standard API errors
Code | Description |
100 | Service temporarily unavailable. |
203 | Missing argument. |
300 | Invalid API key. |
API Calls
All parameters are passed through HTTP GET or POST methods. All reponses are returned in JSON format.
Authentication
login
- Description
- Creates new API session and returns a new API key, that must be used with subsequent requests. Upon successfult login, user details and available homes are return. ("homes" object structure explained in "homes.list" request).
- URL Structure
https://api.istabai.com/2/login.json?email=myemail@example.com&password=mypassword
- Parameters
-
email - Users email.
password - Users password.
- Sample Response
{ "timestamp": 1715877266, "user": { "id": 100, "name": "John Doe", "api_key": "1a79a4d60de6718e8e5b326e338ae533", "homes": 1 }, "homes": [ { "id": 200, "name": "My Home", "rooms": 3, "last_motion": null, "mode": "DAY", "next_mode": null, "warnings": 0, "pro": true } ] }
- Errors
-
Code Description 300 Invalid email or password.
Homes
homes.list
- Description
- Lists all available homes for current user.
- URL Structure
https://api.istabai.com/2/homes.list.json?api_key=1a79a4d60de6718e8e5b326e338ae533
- Parameters
-
api_key - Users API key.
- Sample Response
{ "timestamp": 1715877266, "homes": [ { "id": 200, "name": "My Home", "rooms": 3, "last_motion": null, "mode": "DAY", "next_mode": null, "warnings": 0, "pro": true } ] }
homes.warnings
- Description
- Returns textual device warnings for specified home.
- URL Structure
https://api.istabai.com/2/homes.warnings.json?api_key=1a79a4d60de6718e8e5b326e338ae533&home_id=200&lang=EN
- Parameters
-
api_key - Users API key.
home_id - Home ID for which to request warnings.
lang - (Optional) Language in which to return warnings (Available languages: EN, LV, RU)
- Sample Response
{ "language": "EN", "warnings": [ { "text": "The movement sensor (#300 - Bedroom) isn't connecting to the base station. Check the battery level or its location." } ] }
- Errors
-
Code Description 404 Home with specified ID was not found.
homes.rename
- Description
- Rename home.
- URL Structure
https://api.istabai.com/2/homes.rename.json?api_key=1a79a4d60de6718e8e5b326e338ae533&home_id=200&name=Vacation+House
- Parameters
-
api_key - Users API key.
home_id - Home ID for which to request warnings.
name - New name for specified home
- Sample Response
{ "status": true }
- Errors
-
Code Description 404 Home with specified ID was not found.
homes.set_mode
- Description
- Switches ECO mode on/off and switches automatic mode switching using your schedule.
- URL Structure
https://api.istabai.com/2/homes.set_mode.json?api_key=1a79a4d60de6718e8e5b326e338ae533&home_id=200&eco=1
- Parameters
-
api_key - Users API key.
home_id - Home ID for which to request warnings.
eco - (Optional) Switch the ECO mode.
auto - (Optional) Switch automatic mode switching using your schedule.
- Sample Response
{ "timestamp": 1715877266, "homes": [ { "id": 200, "name": "My Home", "rooms": 3, "last_motion": null, "mode": "ECO", "next_mode": null, "warnings": 0, "pro": true } ] }
- Errors
-
Code Description 404 Home with specified ID was not found.
Rooms
rooms.list
- Description
- Lists all available rooms for specified home.
- URL Structure
https://api.istabai.com/2/rooms.list.json?api_key=1a79a4d60de6718e8e5b326e338ae533&home_id=200
- Parameters
-
api_key - Users API key.
home_id - Home ID for which to request warnings.
- Sample Response
{ "timestamp": 1715877266, "rooms": [ { "id": 5502, "read_only": false, "name": "Bedroom", "temperature": 20.1, "min_temperature": 10, "max_temperature": 25, "set_temperature": { "day": 23.6, "night": 10, "eco": 16.3, "temp": 16.1 }, "temperature_eta_multipliers": [ { "from": 10, "to": 15, "heatup": 60, "cooldown": 50 }, { "from": 15, "to": 20, "heatup": 120, "cooldown": 100 }, { "from": 20, "to": 25, "heatup": 180, "cooldown": 200 } ], "device": { "faulty": false, "battery": 0.35, "charging": false, "signal": 0.5, "last_data": 1389950790 }, "last_motion": null }, { "id": 5501, "read_only": false, "name": "Living Room", "temperature": 22.4, "min_temperature": 10, "max_temperature": 25, "set_temperature": { "day": 21.6, "night": 10, "eco": 22, "temp": 25 }, "temperature_eta_multipliers": [ { "from": 10, "to": 15, "heatup": 60, "cooldown": 50 }, { "from": 15, "to": 20, "heatup": 120, "cooldown": 100 }, { "from": 20, "to": 25, "heatup": 180, "cooldown": 200 } ], "device": { "faulty": false, "battery": 0.8, "charging": false, "signal": 0.75, "last_data": 1389950790 }, "last_motion": null } ], "home": { "id": 5116, "name": "My Home", "rooms": 2, "last_motion": null, "mode": "NIGHT", "next_mode": { "mode": "ECO", "starts": 1389971400, "enabled": true }, "info_string": "", "warnings": 0, "pro": true } }
rooms.set_temperature
- Description
- Sets the temperature for specified room and mode.
- URL Structure
https://api.istabai.com/2/rooms.set_temperature.json?api_key=1a79a4d60de6718e8e5b326e338ae533&room_id=300&temperature=22.5&mode=DAY
- Parameters
-
api_key - Users API key.
room_id - Room ID for which to set the new temperature.
temperature - Set temperature in celsius.
mode - (Optional) Which modes temperature to changes (Possible values: DAY, NIGHT, ECO). If not specified, temperature is changed for current mode.
rooms.rename
- Description
- Rename room.
- URL Structure
https://api.istabai.com/2/rooms.rename.json?api_key=1a79a4d60de6718e8e5b326e338ae533&room_id=300&name=Bedroom
- Parameters
-
api_key - Users API key.
room_id - Room ID for which to change name.
name - New name for specified room
- Sample Response
{ "status": true }
- Errors
-
Code Description 404 Room with specified ID was not found.
Mode Timepoints
mode_timepoints.list
- Description
- Lists all the timpoints that make up specified homes schedule.
- URL Structure
https://api.istabai.com/2/mode_timepoints.list.json?
- Parameters
-
api_key - Users API key.
home_id - Home ID.
- Errors
-
Code Description 404 Home with specified ID was not found.
mode_timepoints.add
- Description
- Adds a timpoint to specified homes schedule.
- URL Structure
https://api.istabai.com/2/mode_timepoints.add.json?
mode_timepoints.updated
- Description
- Updates specified timepoint.
- URL Structure
https://api.istabai.com/2/mode_timepoints.updated.json?
mode_timepoints.remove
- Description
- Removes a timpoint to specified homes schedule.
- URL Structure
https://api.istabai.com/2/mode_timepoints.remove.json?
Devices
devices.list
- Description
- Lists all devices and their parameters that are associtated with specified home.
- URL Structure
https://api.istabai.com/2/devices.list.json?
devices.scan
- Description
- Scans for new devices. Must be reloaded repetedly.
- URL Structure
https://api.istabai.com/2/devices.scan.json?
devices.assign_room
- Description
- Assigns device to a room.
- URL Structure
https://api.istabai.com/2/devices.assign_room.json?
devices.set_relay_state
- Description
- Switches a relay on specified device. Note that you can only switch relays that are not associtated with radiators (rooms) / not used for heating.
- URL Structure
https://api.istabai.com/2/devices.set_relay_state.json?