English Latvian Russian Lithuanian Estonian Polish Danish
General Notes

Authentication

login

Homes

homes.list homes.warnings homes.rename homes.set_mode

Rooms

rooms.list rooms.set_temperature rooms.rename

Mode Timepoints

mode_timepoints.list mode_timepoints.add mode_timepoints.updated mode_timepoints.remove

Devices

devices.list devices.scan devices.assign_room devices.set_relay_state

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": 1713853751,
    "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": 1713853751,
    "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": 1713853751,
    "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": 1713853751,
    "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?