REST API¶
The REST APIs are undergoing active development, so some of the below APIs may change in time. APIs marked as (upcoming) are yet to be added.
/api/info¶
Information about LedFx
GET
Returns basic information about the LedFx instance as JSON
{
"url": "http://127.0.0.1:8888",
"name": "LedFx",
"version": "0.3.0"
}
/api/config¶
Endpoint for managing LedFx Configuration
GET
Returns the current configuration for LedFx as JSON A GET with no request body will return LedFx’s full configuration.
You may instead ask for any number of the config keys:
host
port
port_s
dev_mode
configuration_version
scan_on_startup
visualisation_fps
visualisation_maxlen
audio
melbanks
wled_preferences
devices
virtuals
integrations
scenes
user_presets
ledfx_presets
example: Get LedFx audio configuration
"audio"
example: Get LedFx audio, devices, and scenes configuration
["audio", "devices", "scenes"]
PUT
Updates LedFx configuration with any permitted keys. LedFx will handle the update and restart if necessary. Generally, updating any core config key will trigger a restart.
example:
{
"audio": {
"min_volume": 0.3
},
"dev_mode": true,
"visualisation_fps": 50,
"port": 8080
}
POST
Set full LedFx config. You must provide a full, valid config. LedFx will restart to apply the config. To simply update a part of the config, use PUT
DELETE
Resets LedFx’s config to default values and restarts.
Warning This will irreversibly delete all your devices, settings, etc.
/api/log¶
LedFx Logging
GET
Opens a websocket connection through which realtime LedFx logging info will be sent.
/api/schema/¶
LedFx Schema Api
GET /api/schema/
Get JSON schemas specifically defining the kind of data LedFx’s API expects. A GET with no request body will return all of LedFx’s schemas LedFx uses schemas to validate the following:
devices
effects
integrations
virtuals
audio
melbanks
wled_preferences
core
Like with the /api/config endpoint, you may instead ask for spefific schemas
example: Get LedFx audio schema
"audio"
example: Get LedFx devices and effects schema
["devices", "effects"]
/api/schema/<schema_type>¶
Query a specific LedFx schema with the matching schema_type as JSON
GET /api/schema/<schema_type>
Returns the LedFx schema with the matching schema_type as JSON
devices: Returns all the devices registered with LedFx
effects: Returns all the valid schemas for an LedFx effect
integrations: Returns all the integrations registered with LedFx
/api/devices¶
Query and manage devices connected to LedFx
GET
Get configuration of all devices
POST
Adds a new device to LedFx based on the provided JSON configuration
/api/devices/<device_id>¶
Query and manage a specific device with the matching device_id as JSON
GET
Returns information about the device
PUT
Modifies the information pertaining to the device and returns the new device as JSON
DELETE
Deletes a device with the matching device_id
/api/effects¶
Query and manage all effects
GET
Returns all the effects currently created in LedFx as JSON
POST (upcoming)
Create a new Effect based on the provided JSON configuration
/api/effects/<effect_id>¶
Query and manage a specific effect with the matching effect_id as JSON
GET
Returns information about the effect
PUT (upcoming)
Modifies the configuration of the effect and returns the new configuration as JSON
DELETE (upcoming)
Deletes the effect with the matching effect_id.
/api/virtuals¶
Query and manage virtuals connected to LedFx
GET
Get configuration of all virtuals
POST
Adds a new virtual to LedFx based on the provided JSON configuration
/api/virtuals/<virtual_id>¶
Query and manage a specific virtual with the matching virtual_id as JSON
GET
Returns information about the virtual
PUT
Set a virtual to active or inactive. Must evaluate to True or False with python’s bool() (eg, true, 1, ..)
example:
{
"active": false
}
POST
Update a virtual’s segments configuration. Format is a list of lists in segment order.
[[id, start, end, invert], …]
id: valid device id start: first pixel on the device for this segment end: last pixel on the device for this segment (inclusive) invert: invert this segment when it is mapped onto the device
example:
{
"segments": [
["my_device", 0, 49, false],
["my_other_device", 0, 99, false],
["my_device", 50, 99, false]
]
}
This would end up with a virtual appearing on the devices as so:
[---first 50px of effect---][---last 50px of effect---] [---------------middle 100px of effect----------------]
[-------------------my_device (100px)-----------------] [---------------my_other_device (100px)---------------]
another example:
{
"segments": [
["my_device", 0, 9, false],
["my_device", 20, 79, false],
["my_device", 90, 99, false]
]
}
This would end up with a virtual appearing on the devices as so:
[ 10px ] [------ 60px of effect ------] [ 10px ]
[-------------------my_device (100px)-----------------]
DELETE
Deletes a virtual with the matching virtual_id
/api/virtuals/{virtual_id}/effects¶
Endpoint linking virtuals to effects with the matching virtual_id as JSON
GET
Returns the active effect config of a virtual
PUT
Update the active effect config of a virtual based on the provided JSON configuration If config given is “RANDOMIZE”, the active effect config will be automatically generated to random values
POST
Set the virtual to a new effect based on the provided JSON configuration
DELETE
Clear the active effect of a virtual
/api/virtuals/<virtual_id>/presets¶
Endpoint linking virtuals to effect presets (pre-configured effect configs) with the matching virtual_id as JSON
GET
Get preset effect configs for active effect of a virtual
PUT
Set active effect config of virtual to a preset
{
"category": "user_presets",
"effect_id": "wavelength",
"preset_id": "my_wavelength_preset"
}
POST
Save configuration of virtual’s active effect as a custom preset for that effect
DELETE
Clear effect of a virtual
/api/effects/<effect_id>/presets¶
Endpoint for querying and managing presets (pre-configured effect configs) for each effect with the matching effect_id as JSON
GET
Get all presets for an effect
GET
Rename a preset
DELETE
Delete a preset
/api/scenes¶
Endpoint for managing scenes. Active effects and configs of all devices can be saved as a “scene”.
GET
Get all saved scenes
PUT
Set effects and configs of all devices to those specified in a scene
POST
Save effect configuration of devices as a scene
DELETE
Delete a scene
/api/integrations¶
Endpoint for managing integrations. Integrations are written to allow ledfx to communicate with other software, and vice versa.
GET
Get info of all integrations Optional, send request body to get specific info of integrations Any of: [“id”, “type”, “active”, “status”, “data”, “config”]
example:
{
"info":"status"
}
STATUS REFERENCE 0: disconnected 1: connected 2: disconnecting 3: connecting
PUT
Toggle an integration on or off
example:
{
"id": "myqlc"
}
POST
Create a new integration, or update an existing one
{
"type": "qlc",
"config": {
"description": "QLC Test",
"ip_address": "127.0.0.1",
"name": "myQLC+",
"port": 9999
}
}
{
"type": "spotify",
"config": {
"description": "Spotify triggers for party",
"name": "Party Spotify"
}
}
DELETE
Delete an integration, erasing all its configuration and data.
{
"id": "myqlc"
}
NOTE: This does not turn off the integration, it deletes it entirely! (though it will first turn off..)
/api/integrations/qlc/<integration_id>¶
Endpoint for querying and managing a QLC integration.
GET
Returns info from the QLC+ integration.
Specify “info”, one of: ["event_types", "qlc_widgets", "qlc_listeners"]
event_types: retrieves a list of all the types of events and associated filters a qlc listener can subscribe to
qlc_widgets: retrieves a list of all the widgets that can be modified, formatted as [(ID, Type, Name),…] for “type”:
“Buttons” can be set to either off (0) or on (255)
“Audio Triggers” are either off (0) or on (255)
“Sliders” can be anywhere between 0 and 255
qlc_listeners: retrieves a list of all of the events that QLC is listening to, and their associated widget value payloads
{
"info": "qlc_listeners"
}
PUT
Toggle a QLC+ event listener on or off, so that it will or will not send its payload to set QLC+ widgets
{
"event_type": "scene_set",
"event_filter": {
"scene_name": "My Scene"
}
}
POST
Add a new QLC event listener and QLC+ payload or update an existing one if it exists with same event_type and event_filter The “qlc_payload” is a dict of {“widget_id”: value} that will be sent to QLC+
{
"event_type": "scene_set",
"event_filter": {
"scene_name": "My Scene"
},
"qlc_payload": {
"0":255,
"1":255,
"2":169
}
}
DELETE
Delete a QLC event listener, and associated payload data.
{
"event_type": "scene_set",
"event_filter": {
"scene_name": "My Scene"
}
}
NOTE: This does not turn off the integration, it deletes it entirely! (though it will first turn off..)
/api/integrations/spotify/<integration_id>¶
Endpoint for querying and managing a Spotify integration.
GET
Get all the song triggers
PUT
Update a song trigger [TODO]
POST
Create a new song trigger
{
"scene_id": "my_scene",
"song_id": "347956287364597",
"song_name": "Really Cool Song",
"song_position": "43764",
}
DELETE
Delete a song trigger
{
"trigger_id": "Really Cool Song - 43764",
}
WebSocket API¶
In addition to the REST APIs LedFx has a WebSocket API for streaming realtime data. The primary use for this is for things like effect visualizations in the frontend.
Will document this further once it is more well defined. The general structure will be event registration based.