led-controller/docs/API.md

# LED Controller API Specification

**Base URL:** `http://device-ip/` or `http://192.168.4.1/` (when in AP mode)  
**Protocol:** HTTP/1.1  
**Content-Type:** `application/json`

## Presets API

### GET /presets

List all presets.

**Response:** `200 OK`
```json
{
  "preset1": {
    "name": "preset1",
    "pattern": "on",
    "colors": [[255, 0, 0]],
    "delay": 100,
    "n1": 0,
    "n2": 0,
    "n3": 0,
    "n4": 0,
    "n5": 0,
    "n6": 0,
    "n7": 0,
    "n8": 0
  }
}
```

### GET /presets/{name}

Get a specific preset by name.

**Response:** `200 OK`
```json
{
  "name": "preset1",
  "pattern": "on",
  "colors": [[255, 0, 0]],
  "delay": 100,
  "n1": 0,
  "n2": 0,
  "n3": 0,
  "n4": 0,
  "n5": 0,
  "n6": 0,
  "n7": 0,
  "n8": 0
}
```

**Response:** `404 Not Found`
```json
{
  "error": "Preset not found"
}
```

### POST /presets

Create a new preset.

**Request Body:**
```json
{
  "name": "preset1",
  "pattern": "on",
  "colors": [[255, 0, 0]],
  "delay": 100,
  "n1": 0,
  "n2": 0,
  "n3": 0,
  "n4": 0,
  "n5": 0,
  "n6": 0,
  "n7": 0,
  "n8": 0
}
```

**Response:** `201 Created` - Returns the created preset

**Response:** `400 Bad Request`
```json
{
  "error": "Name is required"
}
```

**Response:** `409 Conflict`
```json
{
  "error": "Preset already exists"
}
```

### PUT /presets/{name}

Update an existing preset.

**Request Body:**
```json
{
  "delay": 200,
  "colors": [[0, 255, 0]]
}
```

**Response:** `200 OK` - Returns the updated preset

**Response:** `404 Not Found`
```json
{
  "error": "Preset not found"
}
```

### DELETE /presets/{name}

Delete a preset.

**Response:** `200 OK`
```json
{
  "message": "Preset deleted successfully"
}
```

**Response:** `404 Not Found`
```json
{
  "error": "Preset not found"
}
```

## Profiles API

### GET /profiles

List all profiles.

**Response:** `200 OK`
```json
{
  "profile1": {
    "name": "profile1",
    "description": "Profile description",
    "scenes": []
  }
}
```

### GET /profiles/{name}

Get a specific profile by name.

**Response:** `200 OK`
```json
{
  "name": "profile1",
  "description": "Profile description",
  "scenes": []
}
```

**Response:** `404 Not Found`
```json
{
  "error": "Profile not found"
}
```

### POST /profiles

Create a new profile.

**Request Body:**
```json
{
  "name": "profile1",
  "description": "Profile description",
  "scenes": []
}
```

**Response:** `201 Created` - Returns the created profile

**Response:** `400 Bad Request`
```json
{
  "error": "Name is required"
}
```

**Response:** `409 Conflict`
```json
{
  "error": "Profile already exists"
}
```

### PUT /profiles/{name}

Update an existing profile.

**Request Body:**
```json
{
  "description": "Updated description"
}
```

**Response:** `200 OK` - Returns the updated profile

**Response:** `404 Not Found`
```json
{
  "error": "Profile not found"
}
```

### DELETE /profiles/{name}

Delete a profile.

**Response:** `200 OK`
```json
{
  "message": "Profile deleted successfully"
}
```

**Response:** `404 Not Found`
```json
{
  "error": "Profile not found"
}
```

## Scenes API

### GET /scenes

List all scenes. Optionally filter by profile using query parameter.

**Query Parameters:**
- `profile` (optional): Filter scenes by profile name

**Example:** `GET /scenes?profile=profile1`

**Response:** `200 OK`
```json
{
  "profile1:scene1": {
    "name": "scene1",
    "profile_name": "profile1",
    "description": "Scene description",
    "transition_time": 0,
    "devices": [
      {"device_name": "device1", "preset_name": "preset1"},
      {"device_name": "device2", "preset_name": "preset2"}
    ]
  }
}
```

### GET /scenes/{profile_name}/{scene_name}

Get a specific scene.

**Response:** `200 OK`
```json
{
  "name": "scene1",
  "profile_name": "profile1",
  "description": "Scene description",
  "transition_time": 0,
  "devices": [
    {"device_name": "device1", "preset_name": "preset1"},
    {"device_name": "device2", "preset_name": "preset2"}
  ]
}
```

**Response:** `404 Not Found`
```json
{
  "error": "Scene not found"
}
```

### POST /scenes

Create a new scene.

**Request Body:**
```json
{
  "name": "scene1",
  "profile_name": "profile1",
  "description": "Scene description",
  "transition_time": 0,
  "devices": [
    {"device_name": "device1", "preset_name": "preset1"},
    {"device_name": "device2", "preset_name": "preset2"}
  ]
}
```

**Response:** `201 Created` - Returns the created scene

**Response:** `400 Bad Request`
```json
{
  "error": "Name is required"
}
```
or
```json
{
  "error": "Profile name is required"
}
```

**Response:** `409 Conflict`
```json
{
  "error": "Scene already exists"
}
```

### PUT /scenes/{profile_name}/{scene_name}

Update an existing scene.

**Request Body:**
```json
{
  "transition_time": 500,
  "description": "Updated description"
}
```

**Response:** `200 OK` - Returns the updated scene

**Response:** `404 Not Found`
```json
{
  "error": "Scene not found"
}
```

### DELETE /scenes/{profile_name}/{scene_name}

Delete a scene.

**Response:** `200 OK`
```json
{
  "message": "Scene deleted successfully"
}
```

**Response:** `404 Not Found`
```json
{
  "error": "Scene not found"
}
```

### POST /scenes/{profile_name}/{scene_name}/devices

Add a device assignment to a scene.

**Request Body:**
```json
{
  "device_name": "device1",
  "preset_name": "preset1"
}
```

**Response:** `200 OK` - Returns the updated scene

**Response:** `400 Bad Request`
```json
{
  "error": "Device name and preset name are required"
}
```

**Response:** `404 Not Found`
```json
{
  "error": "Scene not found"
}
```

### DELETE /scenes/{profile_name}/{scene_name}/devices/{device_name}

Remove a device assignment from a scene.

**Response:** `200 OK` - Returns the updated scene

**Response:** `404 Not Found`
```json
{
  "error": "Scene not found"
}
```

## Patterns API

### GET /patterns

Get the list of available pattern names.

**Response:** `200 OK`
```json
["on", "bl", "cl", "rb", "sb", "o"]
```

### POST /patterns

Add a new pattern name to the list.

**Request Body:**
```json
{
  "name": "new_pattern"
}
```

**Response:** `201 Created` - Returns the updated list of patterns
```json
["on", "bl", "cl", "rb", "sb", "o", "new_pattern"]
```

**Response:** `400 Bad Request`
```json
{
  "error": "Name is required"
}
```

**Response:** `409 Conflict`
```json
{
  "error": "Pattern already exists"
}
```

### DELETE /patterns/{name}

Remove a pattern name from the list.

**Response:** `200 OK`
```json
{
  "message": "Pattern deleted successfully"
}
```

**Response:** `404 Not Found`
```json
{
  "error": "Pattern not found"
}
```

## Error Responses

All endpoints may return the following error responses:

**400 Bad Request** - Invalid request data
```json
{
  "error": "Error message"
}
```

**404 Not Found** - Resource not found
```json
{
  "error": "Resource not found"
}
```

**409 Conflict** - Resource already exists
```json
{
  "error": "Resource already exists"
}
```

**500 Internal Server Error** - Server error
```json
{
  "error": "Error message"
}
```