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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

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

---

Scenes

GET /housekeeping/scenes

List available scenes.

Response:

{
  "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:

{
  "success": true,
  "scene_id": "scene.movie_night",
  "message": "Scene activated"
}

---

Scripts

GET /housekeeping/scripts

List available scripts/sequences.

Response:

{
  "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):

{
  "variables": {
    "brightness_level": 50,
    "target_room": "bedroom"
  }
}

Response:

{
  "success": true,
  "script_id": "script.bedtime_routine",
  "message": "Script executed"
}

---

Automations

GET /housekeeping/automations

List automations and their enabled/disabled status.

Response:

{
  "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:

{
  "enabled": true
}

Response:

{
  "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:

{
  "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:

{
  "status": "healthy",
  "connected": true,
  "platform": "home_assistant",
  "version": "2024.12.0"
}

---

Error Responses

All endpoints should return consistent error responses:

{
  "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.