API Access

All the API endpoints are on the base URL http://api.twitchbots.info/v2/. 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.

All _links are also sent in the Link header.

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/:id

Replace :id with the Twitch ID of the user to check.

Response

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

GET http://api.twitchbots.info/v2/bot/19264788
{
    "id": "19264788",
    "username": "nightbot",
    "type": 1,
    "channelID": null,
    "channelName": null,
    "lastUpdate": "2016-12-28T06:56:15+01:00",
    "_links": {
        "canonical": "http://api.twitchbots.info/v2/bot/19264788",
        "alternate": "https://twitchbots.info/bots/nightbot",
        "help": "https://twitchbots.info/api#bot_id"
        "type": "http://api.twitchbots.info/v2/type/1",
    }
}

/bot

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. -1 returns all bots without a type.
inactive
When set to 1 or similar includes bots with inactive types in the response. Ignored when type is set.
multiChannel
When set to 1 or similar only returns bots that may be in multiple channels
ids
Comma separated list of IDs to check. At most 100 IDs are considered per request.

Response

GET http://api.twitchbots.info/v2/bot
{
    "bots": [
        {
            "id": "19264788",
            "username": "nightbot",
            "type": 1,
            "channelID": null,
            "channelName": null,
            "lastUpdate": "2016-12-28T06:56:15+01:00",
            "_links": {
                "canonical": "http://api.twitchbots.info/v2/bot/19264788"
                "alternate": "https://twitchbots.info/bots/nightbot",
                "help": "https://twitchbots.info/api#bot_id"
                "type": "http://api.twitchbots.info/v2/type/1",
            }
        },
        ...
    ],
    "total": 130,
    "_links": {
        "next": "http://api.twitchbots.info/v2/bot?offset=100&limit=100",
        "prev": null,
        "canonical": "http://api.twitchbots.info/v2/bot?offset=0&limit=100",
        "alternate": "https://twitchbots.info/bots",
        "help": "https://twitchbots.info/api#bot"
    }
}
GET http://api.twitchbots.info/v2/bot?type=1
{
    "bots": [
        {
            "id": "19264788",
            "username": "nightbot",
            "type": 1,
            "channelName": null,
            "channelID": null,
            "lastUpdate": "2016-12-28T06:56:15+01:00",
            "_links": {
                "canonical": "http://api.twitchbots.info/v2/bot/19264788",
                "alterante": "https://twitchbots.info/bots/nightbot",
                "help": "https://twitchbots.info/api#bot_id"
                "type": "http://api.twitchbots.info/v2/type/1",
            }
        }
    ],
    "total": 1,
    "_links": {
        "next": null,
        "prev": null,
        "canonical": "http://api.twitchbots.info/v2/bot?limit=100&type=1&offset=0",
        "type": "http://api.twitchbots.info/v2/type/1",
        "alternate": "https://twitchbots.info/bots",
        "help": "https://twitchbots.info/api#bot"
    }
}
GET http://api.twitchbots.info/v2/bot?ids=19264788
{
    "bots": [
        {
            "id": "19264788",
            "username": "nightbot",
            "type": 1,
            "channelName": null,
            "channelID": null,
            "lastUpdate": "2016-12-28T06:56:15+01:00",
            "_links": {
                "canonical": "http://api.twitchbots.info/v2/bot/19264788",
                "alternate": "https://twitchbots.info/bots/nightbot",
                "help": "https://twitchbots.info/api#bot_id"
                "type": "http://api.twitchbots.info/v2/type/1",
            }
        }
    ],
    "total": 1,
    "_links": {
        "next": null,
        "prev": null,
        "canonical": "http://api.twitchbots.info/v2/bot?ids=19264788&limit=100&offset=0",
        "alternate": "https://twitchbots.info/bots",
        "help": "https://twitchbots.info/api#bot"
    }
}

/type/:id

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

Response

Values for the businessModel key (number or null):

  1. Free
  2. Lifetime license
  3. Subscription
  4. Transaction fees

Values for the apiVersion key (number or null):

  1. Justin.tv API
  2. Kraken v1
  3. Kraken v3
  4. Kraken v5
  5. Helix
  6. Unsupported APIs
GET http://api.twitchbots.info/v2/type/1
{
    "id": 1,
    "name": "Nightbot",
    "multiChannel": true,
    "url": "https://www.nightbot.tv",
    "lastUpdate": "1994-11-05T13:15:30Z",
    "description": "Nightbot, alright",
    "managed": true,
    "customUsername": true,
    "channelsEstimate": 900000,
    "businessModel": 1,
    "hasFreeTier": true,
    "apiVersion": null,
    "sourceCodeURL": null,
    "commandsURL": null,
    "active": true,
    "_links": {
        "canonical": "http://api.twitchbots.info/v2/type/1",
        "bots": "http://api.twitchbots.info/v2/bot?type=1",
        "alternate": "https://twitchbots.info/types/1",
        "help": "https://twitchbots.info/api#type_id"
    }
}

/type

Returns a list of all active types by default.

Parameters

offset
Offset of items, 0 by default
limit
Maximum amount of items to return, 100 by default
inactive
When set to 1 or similar includes inactive types in the response
ids
Comma separated list of IDs to get. At most 100 IDs are considered per request.

Response

GET http://api.twitchbots.info/v2/type
{
    "types": [
        {
            "id": 1,
            "name": "Nightbot",
            "multiChannel": true,
            "url": "https://www.nightbot.tv",
            "lastUpdate": "1994-11-05T13:15:30Z",
            "description": "Nightbot, alright",
            "managed": true,
            "customUsername": true,
            "channelsEstimate": 900000,
            "businessModel": 1,
            "hasFreeTier": true,
            "apiVersion": null,
            "sourceCodeURL": null,
            "commandsURL": null,
            "active": true,
            "_links": {
                "canonical": "http://api.twitchbots.info/v2/type/1",
                "bots": "http://api.twitchbots.info/v2/bot?type=1",
                "alternate": "https://twitchbots.info/types/1",
                "help": "https://twitchbots.info/api#type_id"
            }
        }
    ],
    "total": 1,
    "_links": {
        "next": null,
        "prev": null,
        "canonical": "http://api.twitchbots.info/v2/type?limit=100&offset=0",
        "alternate": "https://twitchbots.info/types",
        "help": "https://twitchbots.info/api#type"
    }
}

/channel/:channelID/bots

Returns a list of bots active in the channel given by the channelID. This does not include all possible bots active in a channel and there is no full record of that in the data set. This is primarily based on the channel field of a bot, which may also be set for bots that can be in multiple channels.

Parameters

offset
Offset of items, 0 by default
limit
Maximum amount of items to return, 100 by default

Response

GET http://api.twitchbots.info/v2/channel/72084450/bots
{
    "bots": [
        {
            "id": "85471494",
            "name": "butler_of_ec0ke",
            "type": 23,
            "channelName": "ec0ke",
            "channelID": "720844850",
            "lastUpdate": "1994-11-05T13:15:30Z",
            "_links": {
                "canonical": "http://api.twitchbots.info/v2/bot/85471494",
                "type": "http://api.twitchbots.info/v2/type/23",
                "alternate": "https://twitchbots.info//bots/butler_of_ec0ke",
                "help": "https://twitchbots.info/api#bot_id"
            }
        }
    ],
    "total": 1,
    "_links": {
        "next": null,
        "prev": null,
        "canonical": "http://api.twitchbots.info/v2/channel/72084450/bots?limit=100&offset=0",
        "help": "https://twitchbots.info/api#channelid_bots"
    }
}

Example Usage