API Documentation

Table Of Contents

• Overview
• Endpoints
  • /status GET
  • /groups GET
  • /groups/:groupName GET
  • /groups/:groupName/users GET
  • /effects GET
  • /effects/:effect GET
  • /effects/:effect/triggers GET
  • /effects/:effect/dependencies GET
  • /effects POST

Overview

As of v4.3, 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 7473. All endpoints have the root http://localhost:7473/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 that status of various Firebot systems, such as if Interactive is currently connected or not

Params

URL

None

Query

None

Example Response

{
   "connections": {
        "interactive": true
    }
}

/groups GET

Description

Lists custom groups saved in Firebot

Params

URL

None

Query

• username=[username] - Filter to groups that contain the given user
• onlynames=true - Only return the name of the groups instead of full group objects (Default: false)

Example Response

[  
    {  
        "groupName":"Test Group",
        "users":[  
            "ebiggz"
        ]
    },
    {  
        "groupName":"Test Group 2",
        "users":[  
            "Firebottle",
            "ThePerry"
        ]
    }
]

/groups/:groupName GET

Description

Get info on a particular group.

Params

URL

• groupName - The name of the group

Query

None

Example Response

{
    "groupName": "Test Group",
    "users": [
        "ebiggz"
    ]
}

/groups/:groupName/users GET

Description

Get the users in a particular group

Params

URL

• groupName - The name of the group

Query

None

Example Response

[
    "ebiggz"
]

/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":"API_BUTTON",
        "name":"API Button",
        "triggers":[  
            "interactive",
            "custom_script",
            "api"
        ],
        "dependencies":[  
            "chat"
        ]
    }
]

/effects/:effect GET

Description

Get info on a particular effect.

Params

URL

• effect - Either the effect name or id.

Query

None

Example Response

{  
    "id":"API_BUTTON",
    "name":"API Button",
    "triggers":[  
        "interactive",         
        "custom_script",
        "api"
    ],
    "dependencies":[  
        "chat"
    ]
}

/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

[  
    "interactive",         
    "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

Note: Currently, it is required that Interactive is connected to run any effects. This will eventually change to take into account effect dependencies

Params

URL

None

Query

None

Body (application/json data type)

{
    "effects": [
        {
            "type": "Chat",
            "chatter": "Streamer",
            "message": "Test chat message"
        }
    ]
}

• effects - List of effect objects that you want Firebot to run.
• username - Optional A string identifier that will be used for certain effects (such as Chat)
• participant - Optional A participant object. If this isn't passed in, certain effects (such as change group) will not work. You can retrieve Participants from Mixer's API.

Example Response

{
    "status": "success"
}