API
There's a websocket based API for communicating with the remote, running on port 946(YIO). Mainly used by the web configurator tool and the YIO Dock.
The API automatically starts on power up and is always running in the background. The API is stopped, before wifi is turned off and started, after wifi is turned on.
Messages are sent in JSON format.
When a client connects, the remote sends a JSON message:
{
"type": "auth_required"
}
The client needs to respond with:
{
"type": "auth",
"token": <token>
}
If you don't provide a token or the token is invalid, you get an error message and the connection is terminated:
{
"type": "auth",
"message": "Invalid token"
}
or
{
"type": "auth",
"message": "Token needed"
}
After successful authentication the client is flagged to be able to communicate with the API, until the client is disconnected. Client needs to authenticate after reconnecting.
Commands are sent to the API as JSON. Not all commands have a response. Commands either return true or false and the payload if there's any.
Response on success:
{
"id": 22,
"success": true,
"type": "result"
}
Response on failure:
{
"id": 22,
"success": false,
"type": "result",
"message": "Optional message for the error."
}
Some commands return a message as part of the failed execution of the command to explain the error.
Command:
{
"type": "reboot"
}
No response. The connection will be disconnected when the remote reboots.
Command:
{
"type": "shutdown"
}
No response. The connection will be disconnected when the remote shuts down.
Command:
{
"id": 1,
"type": "get_config"
}
Response:
{
"id": 1,
"success": true,
"type": "result",
"config": <config>
}
The whole config as json.
Command:
{
"id": 18,
"type": "set_config",
"config": <config>
}
The whole config as json.
Response on success:
{
"id": 18,
"success": true,
"type": "result",
}
Response on failure:
{
"id": 18,
"success": false,
"type": "result",
}
Setting a new config will reload the UI, but won't add entities or integrations to the memory databases. A reboot is needed after uploading a whole new configuration.
Scans for all supported integrations.
Scans for one specific integration.
Command:
{
"id": 22,
"type": "get_supported_integrations"
}
Response on success:
{
"id": 22,
"success": true,
"type": "result",
"supported_integrations": [
"homeassistant",
"homey",
"spotify"
]
}
Response on failure:
{
"id": 22,
"success": false,
"type": "result"
}
Returns the integrations loaded by the remote from the configuration.
Command:
{
"id": 22,
"type": "get_loaded_integrations"
}
Response on success:
{
"id": 22,
"success": true,
"type": "result",
"loaded_integrations": {
"homeassistant": {
"data": [
{
"data": {
"ip": "192.168.0.10:8123",
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9"
},
"friendly_name": "Home Assistant",
"id": "homeassistant"
}
],
"mdns": "_hap._tcp"
},
"spotify": {
"data": [
{
"data": {
"access_token": "lCzbkuM8wGgCo0FiE",
"client_id": "dklfj4897r8912up48fjoi398puo",
"client_secret": "fdajh42907t49128ufioprwh",
"entity_id": "spotify.spotify",
"refresh_token": "zXQktUpnJoyGY"
},
"friendly_name": "Spotify",
"id": "spotify"
}
],
"mdns": "_spotify-connect._tcp"
}
}
}
Response on failure:
{
"id": 22,
"success": false,
"type": "result"
}
Returns the data required to set up an integration.
Command:
{
"id": 22,
"type": "get_integration_setup_data",
"integration: "homeassistant"
}
Response on success:
{
"id": 22,
"success": true,
"type": "result",
"data": {
"ip": "",
"token", ""
}
}
Returns a json with all required data fields for the integration. If no data is required, returns and empty object.
Response on failure:
{
"id": 22,
"success": false,
"type": "result"
}
Add a new integration to the config file and load it to the memory database
Command:
{
"id": 22,
"type": "add_integration",
"config": {
"type": "homeassistant",
"id": "homeassistant_pro",
"friendly_name": "My Home Assistant Server",
"data": {
"ip": "192.168.0.2",
"token": "832748hfjkdfu21ytr79218ohfi2"
}
}
}
type is the type of integration from supported integrations.
id a unique id
friendly_name how the integration should show up on the UI
data required data fields to configure the integration
Response on success:
{
"id": 22,
"success": true,
"type": "result"
}
Response on failure:
{
"id": 22,
"success": false,
"type": "result"
}
Remove an integration from the config file and the memory database
Command:
{
"id": 22,
"type": "remove_integration",
"integration_id": "homeassistant_pro"
}
integration_id is the unique id of the integration
Response on success:
{
"id": 22,
"success": true,
"type": "result"
}
Response on failure:
{
"id": 22,
"success": false,
"type": "result"
}
Adding and removing an integration will be reflected in the UI. (In Settings/Integrations)
Command:
{
"id": 22,
"type": "get_supported_entities"
}
Response on success:
{
"id": 22,
"success": true,
"type": "result",
"supported_entities": [
"light",
"blind",
"media_player",
"climate"
]
}
Response on failure:
{
"id": 22,
"success": false,
"type": "result"
}
Returns the entities loaded by the remote from the configuration.
Command:
{
"id": 22,
"type": "get_loaded_entities"
}
Response on success:
{
"id": 22,
"success": true,
"type": "result",
"loaded_entities": {
"blind": [
{
"area": "Living room",
"entity_id": "cover.living_room_blinds_level",
"friendly_name": "Living room blinds",
"integration": "homeassistant",
"supported_features": [
"OPEN",
"CLOSE",
"STOP",
"POSITION"
]
}
],
"light": [
{
"area": "Entrance",
"entity_id": "light.entrance_lamp_level",
"friendly_name": "Entrance lamp",
"integration": "homeassistant",
"supported_features": [
"BRIGHTNESS"
]
},
{
"area": "Kitchen",
"entity_id": "light.kitchen_dimmer_level",
"friendly_name": "Kitchen lamp",
"integration": "homeassistant",
"supported_features": [
"BRIGHTNESS",
"COLOR"
]
}
]
}
}
Response on failure:
{
"id": 22,
"success": false,
"type": "result"
}
Add a new entity to the config file and load it to the memory database
Command:
{
"id": 22,
"type": "add_entity",
"config": {
"type": "light",
"entity_id": "light.entrance_lamp_level",
"friendly_name": "Entrance lamp",
"integration": "homeassistant",
"supported_features": [
"BRIGHTNESS",
"COLOR"
]
}
}
type is the type of entity
entity_id a unique id
friendly_name how the entity should show up on the UI
integration the integration that handles the entity
supported_features what features the entity has. This information usually comes from the integration. Leave blank if not known.
Response on success:
{
"id": 22,
"success": true,
"type": "result"
}
Response on failure:
{
"id": 22,
"success": false,
"type": "result"
}
Remove an entity from the config file and the memory database
Command:
{
"id": 22,
"type": "remove_entity",
"entity_id": "light.entrance_lamp_level"
}
entity_id is the unique id of the entity
Response on success:
{
"id": 22,
"success": true,
"type": "result"
}
Response on failure:
{
"id": 22,
"success": false,
"type": "result"
}
Adding or removing an entity has no effect on the UI. The user needs to add it to the UI via profiles.
Command:
{
"id": 22,
"type": "get_all_profiles"
}
Response on success:
{
"id": 22,
"success": true,
"type": "result",
"profiles": {
"0": {
"favorites": [
"spotify.spotify",
"light.living_room_lamp_level",
"light.living_room_corner_lamp_level",
"light.kitchen_dimmer_level",
"light.kitchen_table_lamp_level",
"light.desk_lamp"
],
"name": "Marton",
"pages": [
"favorites",
"5",
"1",
"0",
"6",
"settings"
]
},
"1": {
"favorites": [
"media_player.beoplay_m5"
],
"name": "Niels",
"pages": [
"favorites",
"5",
"6"
]
}
}
}
Response on failure:
{
"id": 22,
"success": false,
"type": "result"
}
Activates the profile
Command: { "id": 22, "type": "set_profile", "profile": "0" }
profile is the unique id of the profile
Response on success:
{
"id": 22,
"success": true,
"type": "result"
}
Response on failure:
{
"id": 22,
"success": false,
"type": "result"
}
Create new profile and add it to the config. Command:
{
"id": 22,
"type": "add_profile",
"profile": {
"<uuid>": {
"favorites": [
"media_player.beoplay_m5"
],
"name": "Niels",
"pages": [
"favorites",
"5",
"6"
]
}
}
}
uuid is the unique id of the profile
favorites if no favorites, leave empty array
name name of the profile
pages if no pages, leave empty array
Response on success:
{
"id": 22,
"success": true,
"type": "result"
}
Response on failure:
{
"id": 22,
"success": false,
"type": "result"
}
Command:
{
"id": 22,
"type": "update_profile",
"<uuid>": {
"favorites": [
"media_player.beoplay_m5"
],
"name": "Niels",
"pages": [
"favorites",
"5",
"6"
]
}
}
uuid is the unique id of the profile
favorites if no favorites, leave empty array
name name of the profile
pages if no pages, leave empty array
Response on success:
{
"id": 22,
"success": true,
"type": "result"
}
Response on failure:
{
"id": 22,
"success": false,
"type": "result"
}
Command:
{
"id": 22,
"type": "remove_profile",
"profile_id": 28491
}
id is the unique id of the profile
Response on success:
{
"id": 22,
"success": true,
"type": "result"
}
Response on failure:
{
"id": 22,
"success": false,
"type": "result"
}
Command:
{
"id": 22,
"type": "get_all_pages"
}
Response on success:
{
"id": 22,
"success": true,
"type": "result",
"pages": {
"0": {
"groups": [
"ac9aa887-8d76-440d-b6fa-74ac2cbe8aed",
"ac9aa887-8d76-440d-b6fa-74ac2cbe9aed"
],
"image": "/boot/livingroom.jpg",
"name": "Living room"
},
"1": {
"groups": [
"ac9aa887-8d66-440d-b6fa-74ac2cbe9aed"
],
"image": "/boot/kitchen.jpg",
"name": "Kitchen"
}
}
}
Response on failure:
{
"id": 22,
"success": false,
"type": "result"
}
Create new page and add it to the config. Command:
{
"id": 22,
"type": "add_page",
"page": {
"<uuid>": {
"groups": [
"ac9aa887-8d76-440d-b6fa-74ac2cbe8aed",
"ac9aa887-8d76-440d-b6fa-74ac2cbe9aed"
],
"image": "/boot/livingroom.jpg",
"name": "Living room"
}
}
}
uuid is the unique id of the page
groups the groups the page contains
name name of the page
image header image of the page
Response on success:
{
"id": 22,
"success": true,
"type": "result"
}
Response on failure:
{
"id": 22,
"success": false,
"type": "result"
}
Command:
{
"id": 22,
"type": "update_page",
"<uuid>": {
"groups": [
"ac9aa887-8d76-440d-b6fa-74ac2cbe8aed",
"ac9aa887-8d76-440d-b6fa-74ac2cbe9aed"
],
"image": "/boot/livingroom.jpg",
"name": "Living room"
}
}
uuid is the unique id of the page
groups the groups the page contains
name name of the page
image header image of the page
Response on success:
{
"id": 22,
"success": true,
"type": "result"
}
Response on failure:
{
"id": 22,
"success": false,
"type": "result"
}
Command:
{
"id": 22,
"type": "remove_page",
"page_id": "ac9aa887-8d66-440d-b6fa-74ac2cbe9a2d"
}
id is the unique id of the page
Response on success:
{
"id": 22,
"success": true,
"type": "result"
}
Response on failure:
{
"id": 22,
"success": false,
"type": "result"
}
Command:
{
"id": 22,
"type": "get_all_groups"
}
Response on success:
{
"id": 22,
"success": true,
"type": "result",
"groups": {
"ac9aa887-8d66-440d-b6fa-74ac2cbe9aed": {
"entities": [
"climate.kitchen_radiator_heating_1"
],
"name": "Heating",
"switch": false
},
"ac9aa887-8d66-570d-b6fa-74ac2cbe9aed": {
"entities": [
"climate.bedroom_radiator_heating_1"
],
"name": "Heating",
"switch": false
}
}
}
Response on failure:
{
"id": 22,
"success": false,
"type": "result"
}
Create new group and add it to the config. Command:
{
"id": 22,
"type": "add_group",
"group": {
"<uuid>": {
"entities": [
"climate.bedroom_radiator_heating_1"
],
"name": "Heating"
}
}
}
uuid is the unique id of the group
entitie entities that the group contains
name name of the group
Response on success:
{
"id": 22,
"success": true,
"type": "result"
}
Response on failure:
{
"id": 22,
"success": false,
"type": "result"
}
Command:
{
"id": 22,
"type": "update_group",
"<uuid>": {
"entities": [
"climate.bedroom_radiator_heating_1"
],
"name": "Heating"
}
}
uuid is the unique id of the group
entitie entities that the group contains
name name of the group
Response on success:
{
"id": 22,
"success": true,
"type": "result"
}
Response on failure:
{
"id": 22,
"success": false,
"type": "result"
}
Command:
{
"id": 22,
"type": "remove_group",
"group_id": "ac9aa887-8d66-440d-b6fa-74ac2cbe9aed"
}
id is the unique id of the group
Response on success:
{
"id": 22,
"success": true,
"type": "result"
}
Response on failure:
{
"id": 22,
"success": false,
"type": "result"
}
Command:
{
"id": 22,
"type": "get_languages"
}
Response on success:
{
"id": 22,
"success": true,
"type": "result"
"languages": [
{
"name": "български",
"id": "bg_BG"
},
{
"name": "Català",
"id": "ca_ES"
},
{
"name": "Čeština",
"id": "cs_CZ"
}
]
}
Response on failure:
{
"id": 22,
"success": false,
"type": "result"
}
Command:
{
"id": 22,
"type": "set_language",
"language": "bg_BG"
}
Response on success:
{
"id": 22,
"success": true,
"type": "result"
}
Response on failure:
{
"id": 22,
"success": false,
"type": "result"
}
Command:
{
"id": 22,
"type": "set_auto_brightness",
"value": true
}
value true or false for on and off
Response on success:
{
"id": 22,
"success": true,
"type": "result"
}
Response on failure:
{
"id": 22,
"success": false,
"type": "result"
}
Command:
{
"id": 22,
"type": "set_dark_mode",
"value": true
}
value true or false for on and off
Response on success:
{
"id": 22,
"success": true,
"type": "result"
}
Response on failure:
{
"id": 22,
"success": false,
"type": "result"
}
Home
YIO Remote API
Dock
FAQ
Supporters
Remote Firmware
Dock Firmware
YIO Homepage
YIO Community
YIO Github
YIO Discord Channel
YIO Facebook
YIO Instagram
YIO Twitter
YIO YouTube
YIO Translation
Dock
Remote
Supported IR Extenders
Home Assistant
Homey
openHAB
Roon
Spotify
YIO Dock
Build Environment
Setup Qt IDE
Setup PlatformIO IDE
Developer VM
Setup Buildroot
API
API
WebSocket API
Generic
SSH/SCP
Architecture
Coding Guidelines
Configuration File
Developing Integrations
Entity Types
Logging
Workflow
Git Workflow
Pull Requests
Continuous Integration