Skip to main content
Version: main

HTTP Interface

This guide explains how to manage light groups using the keylightd REST API.

Authentication​

All HTTP API requests must include a valid API key using one of these methods:

Method 1: HTTP Bearer Authentication (Recommended)

curl -H "Authorization: Bearer YOUR_API_KEY" http://localhost:9123/api/v1/groups

Method 2: Custom Header

curl -H "X-API-Key: YOUR_API_KEY" http://localhost:9123/api/v1/groups

Creating Groups​

Create a new group:

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-group"}' \
  http://localhost:9123/api/v1/groups

Create a group with initial lights:

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-group", "light_ids": ["Elgato Key Light ABC1._elg._tcp.local.", "Elgato Key Light XYZ2._elg._tcp.local."]}' \
  http://localhost:9123/api/v1/groups

Response format:

{
  "id": "group-123451",
  "name": "my-group",
  "lights": ["Elgato Key Light ABC1._elg._tcp.local.", "Elgato Key Light XYZ2._elg._tcp.local."]
}

Listing Groups​

List all groups:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  http://localhost:9123/api/v1/groups

Response format:

{
  "group-123451": {
    "id": "group-123451",
    "name": "office-lights",
    "lights": ["Elgato Key Light ABC1._elg._tcp.local.", "Elgato Key Light XYZ2._elg._tcp.local."]
  },
  "group-123452": {
    "id": "group-123452",
    "name": "desk-lights",
    "lights": ["Elgato Key Light ABC1._elg._tcp.local."]
  }
}

Getting Group Information​

Get details of a specific group:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  http://localhost:9123/api/v1/groups/GROUP_ID

Response format:

{
  "id": "group-123451",
  "name": "office-lights",
  "lights": ["Elgato Key Light ABC1._elg._tcp.local.", "Elgato Key Light XYZ2._elg._tcp.local."]
}

Controlling Groups​

Set group state by sending a PUT request to the group's state endpoint:

curl -X PUT \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"on": true, "brightness": 75, "temperature": 3200}' \
  http://localhost:9123/api/v1/groups/GROUP_ID/state

You can include any combination of the following properties in the request body:

  • on (boolean): Power state
  • brightness (integer 0-100): Brightness level
  • temperature (integer 2900-7000): Color temperature in Kelvin

Note: Both the HTTP and Unix socket APIs support setting multiple properties at once.

Power Control​

Turn all lights in a group on:

curl -X PUT \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"on": true}' \
  http://localhost:9123/api/v1/groups/GROUP_ID/state

Turn all lights in a group off:

curl -X PUT \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"on": false}' \
  http://localhost:9123/api/v1/groups/GROUP_ID/state

Brightness Control​

Set brightness for all lights in a group:

curl -X PUT \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"brightness": 80}' \
  http://localhost:9123/api/v1/groups/GROUP_ID/state

Color Temperature Control​

Set color temperature for all lights in a group:

curl -X PUT \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"temperature": 4500}' \
  http://localhost:9123/api/v1/groups/GROUP_ID/state

Modifying Group Membership​

Update the lights in a group:

curl -X PUT \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"light_ids": ["Elgato Key Light ABC1._elg._tcp.local.", "Elgato Key Light XYZ2._elg._tcp.local."]}' \
  http://localhost:9123/api/v1/groups/GROUP_ID/lights

This replaces all lights in the group with the specified lights.

Deleting Groups​

Delete a group:

curl -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY" \
  http://localhost:9123/api/v1/groups/GROUP_ID

This removes the group but does not affect any lights. Successful deletion returns HTTP 204 No Content with no response body.

Advanced Features​

Multiple Group Identifiers​

You can use multiple group identifiers in a single request by separating them with commas:

curl -X PUT \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"on": true}' \
  "http://localhost:9123/api/v1/groups/group-123451,office-lights/state"

This will apply the settings to all matching groups, whether they're matched by ID or name. The server will deduplicate groups if the same group is matched by both ID and name.

Error Handling​

If an operation fails for some lights in a group but succeeds for others, the API will return a 207 Multi-Status response with details about which operations failed.

Response Formats​

Success Response​

Successful state changes return:

{
  "status": "ok"
}

Multi-Status Response​

Partial failures return:

{
  "status": "partial",
  "errors": [
    "Failed to update light-2: device unavailable"
  ]
}

Error Responses​

Error responses include appropriate HTTP status codes with JSON error messages:

{
  "error": "Group not found"
}

Common status codes:

  • 200 - Success
  • 201 - Created (for new groups)
  • 204 - No Content (for deletions)
  • 207 - Multi-Status (partial success)
  • 400 - Bad Request (invalid parameters)
  • 401 - Unauthorized (invalid API key)
  • 404 - Group not found
  • 500 - Internal Server Error

Group Properties​

Controllable Properties​

  • on: Power state (boolean)
  • brightness: Brightness level (integer 0-100)
  • temperature: Color temperature in Kelvin (integer 2900-7000)

Group Information​

  • id: Unique group identifier
  • name: Human-readable group name
  • lights: Array of light IDs in the group