API Documentation

Table Of Contents

• Overview
• Endpoints
  • /status GET
  • /effects GET
  • /effects/:effect GET
  • /effects POST
  • /effects/preset/:presetListId POST/GET

Overview

Firebot hosts a local API that developers can use to get data from Firebot or tell it to run effects.

• The API is hosted on port 7472. All endpoints have the root http://localhost:7472/api/v1
• All responses are in JSON.
• Don't forget that Firebot must be running for the API to be available.

Endpoints

/status GET

Description

Get the connection status of Twitch Chat

Params

URL

None

Query

None

Example Response

{
   "connections": {
        "chat": true
    }
}

/effects GET

Description

Get a list of Firebot effects

Params

URL

None

Query

• trigger=[triggerType] - Filter to effects that support the given trigger
• dependency=[dependencyType] - Filter to effects that require the given dependency
• onlynames=true - Return an array of effect names instead of the full effect objects

Example Response

Note: Example only contains one effect in the list to keep it short. Actual response has a longer list.

[  
    {
        "id": "firebot:chat",
        "name": "Chat",
        "description": "Send a chat message.",
        "icon": "fad fa-comment-lines",
        "categories": [
            "common",
            "chat based"
        ],
        "dependencies": [
            "chat"
        ],
        "triggers": {
            "command": true,
            "custom_script": true,
            "api": true,
            "event": true,
            "hotkey": true,
            "timer": true,
            "counter": true,
            "preset": true,
            "manual": true
        }
    },
]

/effects/:effect GET

Description

Get info on a particular effect.

Params

URL

• effect - Either the effect name or id.

Query

None

Example Response

{
    "id": "firebot:chat",
    "name": "Chat",
    "description": "Send a chat message.",
    "icon": "fad fa-comment-lines",
    "categories": [
        "common",
        "chat based"
    ],
    "dependencies": [
        "chat"
    ],
    "triggers": {
        "command": true,
        "custom_script": true,
        "api": true,
        "event": true,
        "hotkey": true,
        "timer": true,
        "counter": true,
        "preset": true,
        "manual": true
    }
},

/effects/:effect/triggers GET

Description

Get the accepted triggers for an effect

Params

URL

• effect - Either the effect name or id.

Query

None

Example Response

[  
    "chat",         
    "custom_script",
    "api"
]

/effects/:effect/dependencies GET

Description

Get the dependencies for an effect

Params

URL

• effect - Either the effect name or id.

Query

None

Example Response

[  
    "chat"
]

/effects POST

Description

Run a list of effects

Params

URL

None

Query

None

Body (application/json data type)

{
    "effects": {
        "queue": null,
        "list": [
            {
                "type": "firebot:chat",
                "chatter": "Streamer",
                "message": "Test chat message"
            }
        ]
    },
    "triggerData": {
        "username": "ebiggz"
    }
}

• effects.list - A list of effects that you want Firebot to run.
• effects.queue - Optional (string | null) The id of the effect queue that these effects should be placed in
• triggerData - Optional An object containing trigger data used for certain effects (such as Chat)

Example Response

{
    "status": "success"
}

/effects/preset/:presetListId POST/GET

Description

Run a preset effect list

Params

URL

• presetListId - The id of the preset effect list

Query

None

Body

None

Example Response

{
    "status": "success"
}