REST API

The REST API provides a simplified interface for reading device state, controlling devices, and running scenes. Authenticate with an access token (hc_...) or OAuth Bearer token.

Base URL: https://api.homecast.cloud/rest

GET /rest/state

Read the current state of all accessible homes, rooms, and accessories.

curl https://api.homecast.cloud/rest/state \
  -H "Authorization: Bearer hc_your_token"

Query parameters

Parameter	Type	Description
filter_by_home	string	Only accessories in this home (by name)
filter_by_room	string	Only accessories in this room (by name)
filter_by_type	string	Only this accessory type (e.g., lightbulb, thermostat)
filter_by_name	string	Only accessories matching this name

Example with filters:

curl "https://api.homecast.cloud/rest/state?filter_by_type=lightbulb&filter_by_room=Bedroom" \
  -H "Authorization: Bearer hc_your_token"

Response

{
  "homes": [
    {
      "id": "home-uuid",
      "name": "My Home",
      "rooms": [
        {
          "id": "room-uuid",
          "name": "Living Room",
          "accessories": [
            {
              "id": "acc-uuid",
              "name": "Floor Lamp",
              "type": "lightbulb",
              "reachable": true,
              "services": [
                {
                  "type": "lightbulb",
                  "characteristics": [
                    { "type": "on", "value": true },
                    { "type": "brightness", "value": 75 }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

POST /rest/state

Control one or more devices. Send an array of update objects.

curl -X POST https://api.homecast.cloud/rest/state \
  -H "Authorization: Bearer hc_your_token" \
  -H "Content-Type: application/json" \
  -d '[{
    "home": "My Home",
    "room": "Living Room",
    "accessory": "Floor Lamp",
    "on": true,
    "brightness": 80
  }]'

Update fields

Each object must include home, room, and accessory (by name). All other fields are optional.

Field	Type	Description
home	string	Home name (required)
room	string	Room name (required)
accessory	string	Accessory name (required)
on	boolean	Power state
brightness	integer	Brightness 0–100
hue	integer	Color hue 0–360
saturation	integer	Color saturation 0–100
color_temp	integer	Color temperature in mireds
active	boolean	Active state (air purifiers, humidifiers)
heat_target	float	Heating target temperature
cool_target	float	Cooling target temperature
hvac_mode	string	HVAC mode: off, heat, cool, auto
lock_target	integer	Lock state: 1 (secured), 0 (unsecured)
alarm_target	integer	Security alarm target state
speed	integer	Fan speed 0–100
volume	integer	Speaker volume 0–100
mute	boolean	Speaker mute
target	integer	Generic target position 0–100 (blinds, garage doors)

Response

{
  "updated": 1,
  "failed": 0,
  "changes": ["Floor Lamp: on=true, brightness=80"],
  "errors": [],
  "message": "Updated 1 accessories"
}

POST /rest/scene

Execute a HomeKit scene by name.

curl -X POST https://api.homecast.cloud/rest/scene \
  -H "Authorization: Bearer hc_your_token" \
  -H "Content-Type: application/json" \
  -d '{"home": "My Home", "name": "Good Night"}'

Request body

Field	Type	Required	Description
home	string	Yes	Home name
name	string	Yes	Scene name

Response

{ "success": true }

On error:

{ "error": "Scene 'Good Night' not found in home 'My Home'" }

Background endpoints

Manage dashboard background images.

GET /rest/background/presets

List available preset background images.

curl https://api.homecast.cloud/rest/background/presets \
  -H "Authorization: Bearer hc_your_token"

Response:

[
  { "id": "preset-1", "name": "Mountain", "url": "https://...", "category": "nature" }
]

POST /rest/background

Upload a custom background image.

curl -X POST https://api.homecast.cloud/rest/background \
  -H "Authorization: Bearer hc_your_token" \
  -F "file=@background.jpg"

Content-Type: multipart/form-data

Response:

{ "success": true, "url": "https://..." }

DELETE /rest/background

Delete a background image. Pass filename as a query parameter to delete one, or omit to delete all.

curl -X DELETE "https://api.homecast.cloud/rest/background?filename=background.jpg" \
  -H "Authorization: Bearer hc_your_token"

Response:

{ "success": true, "deleted": "background.jpg" }

GET /rest/background/

Serve a background image by its path. Used internally by the dashboard.

Error responses

All REST errors return JSON with an error field:

{ "error": "Scene 'Good Night' not found in home 'My Home'" }

See API Errors for a full list of status codes and common errors.