Skill: nickustinov/itsyhome-control (version 1.0.1)

--- name: itsyhome-control description: "Control and query HomeKit and Home Assistant smart home devices via the Itsyhome macOS app (https://itsyhome.app). Use when the user asks to turn devices on/off, toggle lights, set brightness/temperature/color/fan speed/blind position, lock/unlock doors, open/close garage doors, run scenes, list rooms or devices, check device state or status. Requires Itsyhome Pro running on the same Mac as the OpenClaw gateway. Trigger on any smart home control intent (lights, thermostat, locks, blinds, fans, cameras, scenes, groups)." --- # Itsyhome Control Itsyhome exposes a local HTTP webhook server (default port `8423`) and a URL scheme (`itsyhome://`). **Prerequisites:** Itsyhome Pro, webhook server enabled in Settings → Webhooks. ## Core Pattern All control and query happens via `curl http://localhost:8423/<action>/<target>`. - Targets use `Room/Device` format or just `DeviceName` - Spaces → `%20` in URLs - On success: `{"success": true}` or JSON data - On failure: `{"error": "..."}` with HTTP 4xx ## Workflow 1. **If target is ambiguous** → `curl http://localhost:8423/list/devices` to find exact names 2. **To check current state** → `curl http://localhost:8423/info/<target>` 3. **To control** → appropriate action endpoint (see references/api.md) 4. **Confirm to user** with what was done; include state if queried ## Quick Reference ```bash # Status curl http://localhost:8423/status # List curl http://localhost:8423/list/rooms curl http://localhost:8423/list/devices curl http://localhost:8423/list/devices/Kitchen # Query curl http://localhost:8423/info/Office/Spotlights # Control curl http://localhost:8423/toggle/Office/Spotlights curl http://localhost:8423/on/Kitchen/Light curl http://localhost:8423/brightness/50/Bedroom/Lamp curl http://localhost:8423/scene/Goodnight ``` For the full endpoint list, all control actions, and URL scheme reference: see [references/api.md](references/api.md).

path: references/api.md
content: # Itsyhome Webhook API Reference

Base URL: `http://localhost:8423` (default port, configurable in Settings)

All endpoints respond with JSON. Targets are case-insensitive. Use `%20` for spaces.

## Read Endpoints

### Status
```bash
curl http://localhost:8423/status
# → {"rooms": 5, "devices": 23, "accessories": 18, "reachable": 17, "unreachable": 1, "scenes": 4, "groups": 2}
```

### List
```bash
curl http://localhost:8423/list/rooms
curl http://localhost:8423/list/devices
curl http://localhost:8423/list/devices/Kitchen       # filter by room
curl http://localhost:8423/list/scenes
curl http://localhost:8423/list/groups
curl http://localhost:8423/list/groups/Living%20Room  # filter groups by room
```

### Info (device state)
```bash
curl http://localhost:8423/info/Office/Spotlights     # Room/Device
curl http://localhost:8423/info/Living%20Room         # entire room
curl http://localhost:8423/info/Front%20Door          # single device
# → includes: name, type, reachable, room, state (on, brightness, temperature, locked, etc.)
```

### Debug (raw characteristics)
```bash
curl http://localhost:8423/debug/Office/Spotlights    # specific device
curl http://localhost:8423/debug/all                  # all accessories
curl http://localhost:8423/debug/raw                  # raw HomeKit dump
curl http://localhost:8423/debug/cameras              # all cameras
curl http://localhost:8423/debug/cameras/camera.office # specific camera entity
```

## Control Endpoints

### Power
```bash
curl http://localhost:8423/toggle/Office/Spotlights
curl http://localhost:8423/on/Kitchen/Light
curl http://localhost:8423/off/Bedroom/Lamp
```

### Brightness (0–100)
```bash
curl http://localhost:8423/brightness/50/Bedroom/Lamp
curl http://localhost:8423/brightness/100/Kitchen/Light
```

### Color (hue 0–360, saturation 0–100)
```bash
curl http://localhost:8423/color/120/100/Kitchen/Light   # green, full saturation
curl http://localhost:8423/color/0/100/Living%20Room/Lamp # red
```

### Temperature (degrees, e.g. Celsius)
```bash
curl http://localhost:8423/temp/21/Bedroom/Thermostat
curl http://localhost:8423/temp/20/Living%20Room/AC
```

### Fan Speed (0–100)
```bash
curl http://localhost:8423/speed/50/Living%20Room/Fan
curl http://localhost:8423/speed/100/Bedroom/Fan
```

### Position / Blinds (0–100, 0=closed, 100=open)
```bash
curl http://localhost:8423/position/75/Living%20Room/Blinds
curl http://localhost:8423/position/0/Bedroom/Blinds
```

### Locks
```bash
curl http://localhost:8423/lock/Front%20Door
curl http://localhost:8423/unlock/Front%20Door
```

### Garage / Doors
```bash
curl http://localhost:8423/open/Garage
curl http://localhost:8423/close/Garage
```

### Scenes
```bash
curl http://localhost:8423/scene/Goodnight
curl http://localhost:8423/scene/Movie%20Time
```

## SSE Stream (live state changes)

```bash
curl -N http://localhost:8423/events
# Streams Server-Sent Events with characteristic updates in real time
```

## URL Scheme (no server required)

The `itsyhome://` URL scheme triggers actions without the webhook server:

```bash
open "itsyhome://toggle/Office/Spotlights"
open "itsyhome://on/Kitchen/Light"
open "itsyhome://brightness/50/Bedroom/Lamp"
open "itsyhome://position/75/Living%20Room/Blinds"
open "itsyhome://temp/21/Bedroom/Thermostat"
open "itsyhome://color/120/100/Kitchen/Light"
open "itsyhome://speed/50/Living%20Room/Fan"
open "itsyhome://scene/Goodnight"
open "itsyhome://lock/Front%20Door"
open "itsyhome://unlock/Front%20Door"
open "itsyhome://open/Garage"
open "itsyhome://close/Garage"
```

URL scheme has no read/query capability — use webhook server for status and info.

## Target Format

- `Room/Device` → most specific, preferred
- `DeviceName` → matches across all rooms (may be ambiguous)
- `RoomName` → matches all devices in room (for info/list only)
- URL encode spaces: `Living Room` → `Living%20Room`

## Error Responses

| Status | Meaning |
|--------|---------|
| 200 | Success |
| 400 | Bad request / unsupported action |
| 404 | Device or scene not found |
| 500 | Itsyhome internal error / no data |


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: suspicious | SkillSpector: suspicious (MEDIUM)