Effects

The effects API allows you to retrieve and trigger effects in Firebot.

GET/effects

List all effects

Fetches all available effect definitions. Optionally, filters them by trigger type if the trigger query parameter is provided.

Optional query parameters

Name
trigger
Type
string
Description
The type of trigger to filter the effects by.

Request

GET

/effects

curl http://localhost:7472/api/v1/effects

Response

[
  {
    "id": "effect1",
    "name": "Effect 1",
    "description": "Description of effect 1",
    "triggers": ["someTriggerType"]
  },
  {
    "id": "effect2",
    "name": "Effect 2",
    "description": "Description of effect 2"
  }
]

GET/effects/:effectId

Retrieve an effect

Retrieves the details of a specific effect by its effectId.

URL parameters

Name
effectId
Type
string
Description
The ID of the effect to retrieve.

Request

GET

/effects/:effectId

curl http://localhost:7472/api/v1/effects/someEffectId

Response

{
  "id": "someEffectId",
  "name": "Effect 1",
  "description": "Description of effect 1",
  "triggers": ["someTriggerType"]
}

POST/effects

Trigger effects

Triggers one or more effects with optional trigger data. Requires a request body containing an array of effects to run.

Body properties (JSON)

Name
effects
Type
array
Description
An array of effects to run. Each effect is an object with an id property and any additional properties required by the effect.
Name
triggerData
Type
object
Description
Optional data to pass to the effect triggers. This can be any key-value pairs that the effect triggers may use.

Request

POST

/effects

curl -X POST http://localhost:7472/api/v1/effects \
  -H "Content-Type: application/json" \
  -d '{"effects": [{"id": "effect1"}, {"id": "effect2"}], "triggerData": {"username": "API Call"}}'

Response

{
  "status": "success"
}

GET/effects/preset

List preset effect lists

Lists all preset effect lists, including their IDs and associated arguments.

Request

GET

/effects/preset

curl http://localhost:7472/api/v1/effects/preset

Response

[
  {
    "id": "preset1",
    "name": "Preset 1",
    "args": ["arg1", "arg2"]
  },
  {
    "id": "preset2",
    "name": "Preset 2",
    "args": ["arg1"]
  }
]

POST/effects/preset/:presetListId

Trigger preset effect list

Triggers a preset effect list synchronously (i.e., waits for the effects to complete before responding) with optional arguments and username.

If you want to trigger the preset list asynchronously (i.e., doesn't wait for the effects to complete), append /run to the URL.

URL parameters

Name
presetListId
Type
string
Description
The ID of the preset effect list to trigger.

Body properties (JSON)

Name
username
Type
string
Description
The username to associate with the effect list.
Name
args
Type
object
Description
Optional arguments to pass to the preset effect list.

Request (sync)

POST

/effects/preset/:presetListId

curl -X POST http://localhost:7472/api/v1/effects/preset/somePresetId \
  -H "Content-Type: application/json" \
  -d '{"username": "testuser", "args": {"arg1": "value1", "arg2": "value2"}}'

Request (async)

POST

/effects/preset/:presetListId/run

curl -X POST http://localhost:7472/api/v1/effects/preset/somePresetId/run \
  -H "Content-Type: application/json" \
  -d '{"username": "testuser", "args": {"arg1": "value1", "arg2": "value2"}}'

Response

{
  "status": "success"
}

GET/effects/preset/:presetListId

Trigger preset effect list

Triggers a preset effect list synchronously (i.e., waits for the effects to complete before responding)

If you want to trigger the preset list asynchronously (i.e., doesn't wait for the effects to complete), append /run to the URL.

URL parameters

Name
presetListId
Type
string
Description
The ID of the preset effect list to trigger.

Request (Sync)

GET

/effects/preset/:presetListId

curl GET http://localhost:7472/api/v1/effects/preset/somePresetId

Request (Async)

GET

/effects/preset/:presetListId/run

curl GET http://localhost:7472/api/v1/effects/preset/somePresetId/run

Response

{
  "status": "success"
}