wled-screen-controller-mixed/docs/API.md

WLED Screen Controller API Documentation

Complete REST API reference for the WLED Screen Controller server.

Base URL: http://localhost:8080 API Version: v1

---

Table of Contents

• Health & Info
• Device Management
• Processing Control
• Settings Management
• Calibration
• Metrics

---

Health & Info

GET /health

Health check endpoint.

Response:

{
  "status": "healthy",
  "timestamp": "2026-02-06T12:00:00Z",
  "version": "0.1.0"
}

GET /api/v1/version

Get version information.

Response:

{
  "version": "0.1.0",
  "python_version": "3.11.0",
  "api_version": "v1"
}

GET /api/v1/config/displays

List available displays for screen capture.

Response:

{
  "displays": [
    {
      "index": 0,
      "name": "Display 1",
      "width": 1920,
      "height": 1080,
      "is_primary": true
    }
  ],
  "count": 1
}

---

Device Management

POST /api/v1/devices

Create and attach a new WLED device.

Request:

{
  "name": "Living Room TV",
  "url": "http://192.168.1.100",
  "led_count": 150
}

Response: 201 Created

{
  "id": "device_abc123",
  "name": "Living Room TV",
  "url": "http://192.168.1.100",
  "led_count": 150,
  "enabled": true,
  "status": "disconnected",
  "settings": {
    "display_index": 0,
    "fps": 30,
    "border_width": 10
  },
  "calibration": {
    "layout": "clockwise",
    "start_position": "bottom_left",
    "segments": [...]
  },
  "created_at": "2026-02-06T12:00:00Z",
  "updated_at": "2026-02-06T12:00:00Z"
}

GET /api/v1/devices

List all attached devices.

Response:

{
  "devices": [...],
  "count": 2
}

GET /api/v1/devices/{device_id}

Get device details.

Response: Same as POST response

PUT /api/v1/devices/{device_id}

Update device information.

Request:

{
  "name": "Updated Name",
  "enabled": true
}

DELETE /api/v1/devices/{device_id}

Delete/detach a device.

Response: 204 No Content

---

Processing Control

POST /api/v1/devices/{device_id}/start

Start screen processing for a device.

Response:

{
  "status": "started",
  "device_id": "device_abc123"
}

POST /api/v1/devices/{device_id}/stop

Stop screen processing.

Response:

{
  "status": "stopped",
  "device_id": "device_abc123"
}

GET /api/v1/devices/{device_id}/state

Get current processing state.

Response:

{
  "device_id": "device_abc123",
  "processing": true,
  "fps_actual": 29.8,
  "fps_target": 30,
  "display_index": 0,
  "last_update": "2026-02-06T12:00:00Z",
  "errors": []
}

---

Settings Management

GET /api/v1/devices/{device_id}/settings

Get processing settings.

Response:

{
  "display_index": 0,
  "fps": 30,
  "border_width": 10,
  "color_correction": {
    "gamma": 2.2,
    "saturation": 1.0,
    "brightness": 1.0
  }
}

PUT /api/v1/devices/{device_id}/settings

Update processing settings.

Request:

{
  "display_index": 1,
  "fps": 60,
  "border_width": 15,
  "color_correction": {
    "gamma": 2.4,
    "saturation": 1.2,
    "brightness": 0.8
  }
}

---

Calibration

GET /api/v1/devices/{device_id}/calibration

Get calibration configuration.

Response:

{
  "layout": "clockwise",
  "start_position": "bottom_left",
  "segments": [
    {
      "edge": "bottom",
      "led_start": 0,
      "led_count": 40,
      "reverse": false
    },
    {
      "edge": "right",
      "led_start": 40,
      "led_count": 30,
      "reverse": false
    },
    {
      "edge": "top",
      "led_start": 70,
      "led_count": 40,
      "reverse": true
    },
    {
      "edge": "left",
      "led_start": 110,
      "led_count": 40,
      "reverse": true
    }
  ]
}

PUT /api/v1/devices/{device_id}/calibration

Update calibration.

Request: Same as GET response

POST /api/v1/devices/{device_id}/calibration/test

Test calibration by lighting up specific edge.

Query Parameters:

• edge: Edge to test (top, right, bottom, left)
• color: RGB color array (e.g., [255, 0, 0])

---

Metrics

GET /api/v1/devices/{device_id}/metrics

Get detailed processing metrics.

Response:

{
  "device_id": "device_abc123",
  "processing": true,
  "fps_actual": 29.8,
  "fps_target": 30,
  "uptime_seconds": 3600.5,
  "frames_processed": 107415,
  "errors_count": 2,
  "last_error": null,
  "last_update": "2026-02-06T12:00:00Z"
}

---

Error Responses

All endpoints may return error responses in this format:

{
  "error": "ErrorType",
  "message": "Human-readable error message",
  "detail": {...},
  "timestamp": "2026-02-06T12:00:00Z"
}

Common HTTP Status Codes:

• 200 OK - Success
• 201 Created - Resource created
• 204 No Content - Success with no response body
• 400 Bad Request - Invalid request
• 404 Not Found - Resource not found
• 500 Internal Server Error - Server error

---

Interactive Documentation

The server provides interactive API documentation:

• Swagger UI: http://localhost:8080/docs
• ReDoc: http://localhost:8080/redoc
• OpenAPI JSON: http://localhost:8080/openapi.json