Skip to content

API Documentation

Jump to bottom
CaveMobster edited this page Jan 5, 2022 · 16 revisions

Table Of Contents

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 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/: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/preset/:presetListId POST/GET

Description

Run a preset effect list

Params

URL

  • presetListId - The id of the preset effect list

Query

None

Body

{
    "args": {
        "argName1": "argValue1",
        "argName2": "argValue2"
    }
}

Example Response

{
    "status": "success"
}

/custom-variables GET

Description

Returns an object of objects containing the ttl and value of all custom variables.

Params

URL

None

Query

None

Example Response

{
    "variableName": {
        "t": 0,
        "v": "custom variable value"
    }
}

/custom-variables/:variableName POST/GET

Description

Returns an object with the ttl and the value of the given custom variable, or creates/updates a custom variable by name.

Params

URL

  • variableName - The name of the custom variable

Query

None

Body

{
    "ttl": 0,
    "data": "custom variable value"
}

Example GET Response

{
    "t": 0,
    "v": "custom variable value"
}

/currency GET

Description

Returns an object of currency configs.

Params

URL

None

Query

None

Example Response

{
    "b9e4b340-6e43-11ec-9034-855cfccea1fc": {
        "id": "b9e4b340-6e43-11ec-9034-855cfccea1fc",
        "name": "Points",
        "active": true,
        "payout": 5,
        "interval": 5,
        "limit": 0,
        "transfer": "Allow",
        "bonus": {},
        "$$hashKey": "object:12345"
    }
}

/currency/:currencyName GET

Description

Returns a currency config for the given currency name.

Params

URL

  • currencyName - The name of the currency

Query

None

Example Response

{
    "id": "b9e4b340-6e43-11ec-9034-855cfccea1fc",
    "name": "Points",
    "active": true,
    "payout": 5,
    "interval": 5,
    "limit": 0,
    "transfer": "Allow",
    "bonus": {}
}

/viewers/:userId/currency GET

Description

Returns key value pairs for all currency values a user has, where the key is the currency id and value is the amount.

Params

URL

None

Query

  • username (optional) - Set to true to make Firebot tread :userId as a username instead.

Example Response

{
    "1d563320-47a0-11eb-bf90-3ff408e1e682": 0,
    "b9e4b340-6e43-11ec-9034-855cfccea1fc": 0
}

/viewers/:userId/currency/:currencyId POST/GET

Description

Returns the currency amount for the given currency id or updates the currency for the user with the given amount.

Params

URL

None

Query

  • username (optional) - Set to true to make Firebot tread :userId as a username instead.

Body

setAmount is optional (true by default), and will override the user's currency with the supplied value instead of trying to add it.

{
    "amount": 5,
    "setAmount": true

Example GET Response

0

Firebot Wiki

Common

Advanced

Troubleshooting

Still need help? Come chat with us in the #help channel of our Discord server.

Developers

Clone this wiki locally