tatlock/docs/housekeeping-api-spec.md

# Home Automation API Interface Specification

## Purpose

This document specifies the expected endpoints for a home automation abstraction layer in core-api. These endpoints will be consumed by the Tatlock Housekeeper agent and potentially other projects (scheduler, dashboards).

The goal is to provide a simplified, domain-specific interface for home automation that abstracts away the underlying platform (initially Home Assistant, but swappable).

---

## Endpoints

### Device Discovery

#### `GET /housekeeping/devices`

List available devices.

**Query Parameters:**
- `domain` (optional): Filter by device type (e.g., `light`, `switch`, `climate`, `media_player`)
- `area` (optional): Filter by area/room name

**Response:**
```json
{
  "devices": [
    {
      "entity_id": "light.living_room",
      "name": "Living Room Light",
      "domain": "light",
      "area": "Living Room",
      "state": "on",
      "attributes": {
        "brightness": 255,
        "color_temp": 370
      }
    }
  ]
}
```

---

#### `GET /housekeeping/devices/{entity_id}`

Get detailed state of a specific device.

**Response:**
```json
{
  "entity_id": "light.living_room",
  "name": "Living Room Light",
  "domain": "light",
  "area": "Living Room",
  "state": "on",
  "attributes": {
    "brightness": 255,
    "color_temp": 370,
    "supported_features": ["brightness", "color_temp"]
  },
  "last_changed": "2025-12-16T10:30:00Z"
}
```

---

#### `GET /housekeeping/areas`

List all areas/rooms.

**Response:**
```json
{
  "areas": [
    {"id": "living_room", "name": "Living Room"},
    {"id": "bedroom", "name": "Bedroom"},
    {"id": "kitchen", "name": "Kitchen"}
  ]
}
```

---

### Device Control

#### `POST /housekeeping/devices/{entity_id}/control`

Control a device (turn on, turn off, toggle, or set attributes).

**Request Body:**
```json
{
  "action": "turn_on",
  "brightness": 128,
  "color_temp": 400
}
```

- `action` (required): One of `turn_on`, `turn_off`, `toggle`
- Additional attributes vary by device type (brightness, color_temp, rgb_color, etc.)

**Response:**
```json
{
  "success": true,
  "entity_id": "light.living_room",
  "new_state": "on",
  "message": "Light turned on"
}
```

---

### Scenes

#### `GET /housekeeping/scenes`

List available scenes.

**Response:**
```json
{
  "scenes": [
    {"id": "scene.movie_night", "name": "Movie Night"},
    {"id": "scene.good_morning", "name": "Good Morning"},
    {"id": "scene.all_off", "name": "All Off"}
  ]
}
```

---

#### `POST /housekeeping/scenes/{scene_id}/activate`

Activate a scene.

**Response:**
```json
{
  "success": true,
  "scene_id": "scene.movie_night",
  "message": "Scene activated"
}
```

---

### Scripts

#### `GET /housekeeping/scripts`

List available scripts/sequences.

**Response:**
```json
{
  "scripts": [
    {"id": "script.bedtime_routine", "name": "Bedtime Routine"},
    {"id": "script.welcome_home", "name": "Welcome Home"}
  ]
}
```

---

#### `POST /housekeeping/scripts/{script_id}/run`

Execute a script with optional variables.

**Request Body (optional):**
```json
{
  "variables": {
    "brightness_level": 50,
    "target_room": "bedroom"
  }
}
```

**Response:**
```json
{
  "success": true,
  "script_id": "script.bedtime_routine",
  "message": "Script executed"
}
```

---

### Automations

#### `GET /housekeeping/automations`

List automations and their enabled/disabled status.

**Response:**
```json
{
  "automations": [
    {
      "id": "automation.motion_lights",
      "name": "Motion Lights",
      "enabled": true
    },
    {
      "id": "automation.night_mode",
      "name": "Night Mode",
      "enabled": false
    }
  ]
}
```

---

#### `POST /housekeeping/automations/{automation_id}/toggle`

Enable or disable an automation.

**Request Body:**
```json
{
  "enabled": true
}
```

**Response:**
```json
{
  "success": true,
  "automation_id": "automation.motion_lights",
  "enabled": true,
  "message": "Automation enabled"
}
```

---

### Utility

#### `GET /housekeeping/history`

Get state history for a device.

**Query Parameters:**
- `entity_id` (required): Device to get history for
- `hours` (optional, default 24): Hours of history to retrieve

**Response:**
```json
{
  "entity_id": "light.living_room",
  "history": [
    {
      "state": "on",
      "timestamp": "2025-12-16T10:30:00Z",
      "attributes": {"brightness": 255}
    },
    {
      "state": "off",
      "timestamp": "2025-12-16T08:00:00Z",
      "attributes": {}
    }
  ]
}
```

---

#### `GET /housekeeping/health`

Health check for home automation connection.

**Response:**
```json
{
  "status": "healthy",
  "connected": true,
  "platform": "home_assistant",
  "version": "2024.12.0"
}
```

---

## Error Responses

All endpoints should return consistent error responses:

```json
{
  "error": true,
  "code": "DEVICE_NOT_FOUND",
  "message": "Device light.nonexistent not found"
}
```

Common error codes:
- `DEVICE_NOT_FOUND` - Entity ID doesn't exist
- `INVALID_ACTION` - Unsupported action for device type
- `CONNECTION_ERROR` - Cannot reach home automation platform
- `UNAUTHORIZED` - Invalid or missing credentials

---

## Authentication

All endpoints require authentication via Bearer token in the `Authorization` header.

---

## Consuming Client

The Tatlock project has an existing client (`src/agents/housekeeper/client.py`) that expects these endpoints. No changes to Tatlock are needed once these endpoints are available.

Reference: `CoreAPIClient` class in Tatlock expects these exact endpoint patterns.