All the API endpoints are on the base URL https://api.twitchbots.info/v1/. All endpoints only accept GET requests. The API always returns JSON. Feel free to reuse data returned by this API in your own services and APIs, however please consider contributing relevant data back to this service. All endpoints with a more or less static dataset send an expiration header indicating how long the data is at least expected to be valid. These will be adjusted according to real-world values. If your HTTP library does not honor the Expires header, please honor it manually.

Libraries

For back-end JS developers there are a few pre-built packages on NPM to get data via API:

twitchbots-base
A very basic API implementation with caching.
jetpack-twitchbots
Module for the Firefox Add-on SDK.
twitchbots-node
Ready to use API consumer for node projects.

Errors

The API returns error codes whenever appropriate, like for example invalid parameters. If there are special cases where errors get thrown that's documented in the "Response" section of an endpoint. Some errors will return JSON specifying what went wrong in the following form:

{ "error": "Invalid offset specified", "code": 400 }

Endpoints

/bot/:name

Replace :name with the username of the Twitch user to check.

Response

Responds with a 404 error if the user is not a bot. type is null if unknown.

GET https://api.twitchbots.info/v1/bot/nightbot
{
    "username": "nightbot",
    "twitch_id": "19264788",
    "type": 1,
    "channel": null,
    "channel_id": null,
    "_links": {
        "self": "https://api.twitchbots.info/v1/bot/nightbot",
        "type": "https://api.twitchbots.info/v1/type/1",
        "web": "https://twitchbots.info/bots/nightbot",
        "documentation": "https://twitchbots.info/api#bot_name"
    }
}

/bot/all

Returns all known bots.

Parameters

offset
Offset of items, 0 by default
limit
Maximum amount of items to return, 100 by default
type
Optionally only return bots of the given type ID

Response

GET https://api.twitchbots.info/v1/bot/all
{
    "bots": [
        {
            "twitch_id": "19264788",
            "username": "nightbot",
            "type": 1,
            "channel": null,
            "channel_id": null,
            "_links": {
                "self": "https://api.twitchbots.info/v1/bot/nightbot"
                "type": "https://api.twitchbots.info/v1/type/1",
                "web": "https://twitchbots.info/bots/nightbot",
                "documentation": "https://twitchbots.info/api#bot_name"
            }
        },
        ...
    ],
    "offset": 0,
    "limit": 100,
    "total": 130,
    "_links": {
        "next": "https://api.twitchbots.info/v1/bot/all?offset=100&limit=100",
        "prev": null,
        "self": "https://api.twitchbots.info/v1/bot/all?offset=0&limit=100",
        "web": "https://twitchbots.info/bots",
        "documentation": "https://twitchbots.info/api#bot_all"
    }
}
GET https://api.twitchbots.info/v1/bot/all?type=1
{
    "bots": [
        {
            "username": "nightbot",
            "twitch_id": "19264788",
            "type": 1,
            "channel": null,
            "channel_id": null,
            "_links": {
                "self": "https://api.twitchbots.info/v1/bot/nightbot",
                "type": "https://api.twitchbots.info/v1/type/1",
                "web": "https://twitchbots.info/bots/nightbot",
                "documentation": "https://twitchbots.info/api#bot_name"
            }
        }
    ],
    "offset": 0,
    "limit": 100,
    "total": 1,
    "_links": {
        "next": null,
        "prev": null,
        "self": "https://api.twitchbots.info/v1/bot/all?offset=0&limit=100&type=1",
        "type": "https://api.twitchbots.info/v1/type/1",
        "web": "https://twitchbots.info/bots",
        "documentation": "https://twitchbots.info/api#bot_all"
    }
}

/bot

Check multiple user's bot status. Only returns users that are registered as bots.

Parameters

bots
Comma separated list of usernames to check
offset
Offset of items, 0 by default
limit
Maximum amount of items to return, 100 by default

Response

Note that the next link is not always null when there is no next page, simply because the back-end doesn't know how many results there will be in total.

GET https://api.twitchbots.info/v1/bot?bots=nightbot
{
    "bots": [
        {
            "twitch_id": "19264788",
            "username": "nightbot",
            "type": 1,
            "channel": null,
            "channel_id": null,
            "_links": {
                "self": "https://api.twitchbots.info/v1/bot/nightbot",
                "type": "https://api.twitchbots.info/v1/type/1",
                "web": "https://twitchbots.info/bots/nightbot",
                "documentation": "https://twitchbots.info/api#bot_name"
            }
        }
    ],
    "offset": 0,
    "limit": 100,
    "_links": {
        "next": null,
        "prev": null,
        "self": "https://api.twitchbots.info/v1/bot?bots=nightbot&offset=0&limit=100",
        "web": "https://twitchbots.info/bots",
        "documentation": "https://twitchbots.info/api#bot"
    }
}

/type/:id

Replace :id with the id of the type you want to get.

Response

GET https://api.twitchbots.info/v1/type/1
{
    "id": 1,
    "name": "Nightbot",
    "multiChannel": true,
    "url": "https://www.nightbot.tv",
    "_links": {
        "self": "https://api.twitchbots.info/v1/type/1",
        "bots": "https://api.twitchbots.info/v1/bot/all?type=1",
        "web": "https://twitchbots.info/types/1",
        "documentation": "https://twitchbots.info/api#type_id"
    }
}

Example Usage