API Documentation

BotBlock provides a single API endpoint that allows bot owners to quickly post their server/guild count to all bot lists that we have API data for.
This means the bot owners only ever have to make a single request to update their bot stats on all bot lists.

We have first and third-party libraries created for many major bot development languages that provide easy implementation of the BotBlock API. Check them out or use the documentation below to create your own implementation.

BotBlock does not store any user data at all. All data sent to this API is passed directly onto each list's API as necessary. Authorization tokens are not stored and are only shared with their respective list's API.

Update bot server/guild count

POST /api/count
Content-type: application/json
Request Body
JSON Property Type Required Description
server_count Integer Yes * The server/guild count for your bot.
bot_id Snowflake Yes The ID of your bot.
shard_id Integer No The shard ID for the current count being posted. **
shard_count Integer No The total number of shards for the bot. **
shards Array<Integer> No The server/guild count per shard. **
botlist.space String No Your Authorization token for botlist.space.
botsfordiscord.com String No Your Authorization token for Bots for Discord.
bots.ondiscord.xyz String No Your Authorization token for Bots on Discord.
discord.boats String No Your Authorization token for Discord Boats.
discordboats.club String No Your Authorization token for Discord Boats.
discordbotindex.com String No Your Authorization token for Discord Bot Index.
discordbots.org String No Your Authorization token for Discord Bot List.
discordbotlist.com String No Your Authorization token for Discord Bot List.
discordbotlist.xyz String No Your Authorization token for Discord Bot List.
discordbot.world String No Your Authorization token for Discord Bot World.
bots.discord.pw String No Your Authorization token for Discord Bots.
discordbots.group String No Your Authorization token for Discord Bots Group.
bots.discordlist.app String No Your Authorization token for Discord List App.
discord.services String No Your Authorization token for Discord Services.
discordsbestbots.xyz String No Your Authorization token for Discord's Best Bots.
divinediscordbots.com String No Your Authorization token for Divine Discord Bot List.

* Value is required but will be ignored if 'shards' is posted and the current list accepts a 'shards' value.
** This information is only passed on to bot lists who support it.
This table will automatically update when new bot lists with server count APIs are added to the list.

Response Body
JSON Property Type Description
success Object<Array<Integer, String, String>> All list IDs that successfully posted will be listed here. See below for contents.
failure Object<Array<Integer, String, String>> All list IDs that failed to post will be listed here. See below for contents.

In the success and failure objects, each list ID attempted will be a key with a value that is an array. The first item in the array is the HTTP status code of the response, the second is the string response body and the third item is the body data sent to the list.

If an error occurs prior to posting, a 403 will be returned with a string body containing the error.

Example Response
{
    "success": {
        "thelist.org": [
            200,
            "{\"message\":\"OK\"}",
            "{\"server_count\":200}"
        ],
        "listofbots.com": [
            200,
            "",
            "{\"count\":200}"
        ]
    },
    "failure": {
        "brokenlist.co.uk": [
            500,
            "Bot not found",
            "{\"guilds\":200}"
        ]
    }
}

Get bot information from lists

GET /api/bots/:id
Response Body
JSON Property Type Description
id Snowflake The ID of the bot being fetched.
username String The username of the bot fetched. *
discriminator String The discriminator of the bot fetched. *
owners Array< Snowflake> The IDs of all known owners of the bot. *
server_count Integer The server/guild count for the bot. *
invite String The invite URL for the bot (Discord or custom). *
list_data Object<Array<Any, Integer>> Each list with a known bot GET API endpoint will have all its data returned along with the HTTP status code returned from the request under the key of the BotBlock ID for the list within the list_data property. See below for example.

* These values are calculated based on the most common response (max value for server/guild count, unique values for owners) from all lists' APIs that returned information on the bot being fetched. If no information is gathered these values may be blank.

If an error occurs during the API call, a 403 will be returned with a string body containing the error.

Example Response
{
    "id": "123456789012345678",
    "username": "My Bot",
    "discriminator": "1234",
    "owners": [
        "123456789012345678"
    ],
    "server_count": 500,
    "invite": "https://discordapp.com/oauth2/authorize?client_id=123456789012345678&scope=bot&permissions=8",
    "list_data": {
        "thelist.org": [
            <list data>,
            200
        ],
        "listofbots.com": [
            <list data>,
            200
        ],
        "brokenlist.co.uk": [
            <list data>,
            404
        ]
    }
}

Get all lists' API details

GET /api/lists
Response Body
JSON Property Type Description
<list_id> Object The ID used in BotBlock for the list acts as the key for each property in the response.
<list_id>api_docs String The URL stored for the api docs of the list.
<list_id>api_post String The URL stored for posting server/guild count to the list.
<list_id>api_field String The JSON field name for posting the server/guild count to the list.
<list_id>api_shard_id String The JSON field name for posting the current shard ID to the list.
<list_id>api_shard_count String The JSON field name for posting the bot shard count to the list.
<list_id>api_shards String The JSON field name for posting an array of server counts per shard to the list.
<list_id>api_get String The URL stored for fetching bot information from the list.
Example Response
{
    "thelist.org": {
        "api_docs": "https://thelist.org/api/docs",
        "api_post": "https://thelist.org/api/bot/stats/:id",
        "api_field": "server_count",
        "api_shard_id": "shard_id",
        "api_shard_count": "shard_count",
        "api_shards": null,
        "api_get": "https://thelist.org/api/bot/info/:id"
    },
    "listofbots.com": {
        "api_docs": "https://listofbots.com/docs",
        "api_post": "https://listofbots.com/api/stats/:id",
        "api_field": "guild_count",
        "api_shard_id": null,
        "api_shard_count": null,
        "api_shards": "shards",
        "api_get": null
    }
}

Ratelimits

There is a global ratelimit on the BotBlock API per request source IP address of 5 requests every second.

This API has ratelimits in place based on request source IP address and, where possible, bot ID. This API tries its best to preset the request source IP to the lists' APIs and not our IP address but this API may get ratelimited from lists if it is inundated with requests, therefor our ratelimits are high as to reduce the likelihood of this occurring.

Ratelimits
Route Request Type Limit (requests / time period) per Bot ID
/api/count Valid POST 1 / 120s Yes
/api/bots/:id Any 1 / 1s No
/api/lists Any 1 / 1s No
Response Body & Headers
HTTP Status: 429 Too Many Requests
JSON Property HTTP Header Type Description
retry_after Retry-After Integer How many seconds until the API can be used again.
ratelimit_reset X-Rate-Limit-Reset Integer The unix timestamp when the API can be used again.
ratelimit_ip X-Rate-Limit-IP String The IP address that the API is ratelimiting in this response.
ratelimit_route X-Rate-Limit-Route String The API route that is being ratelimited in this response.
ratelimit_bot_id X-Rate-Limit-Bot-ID Integer The bot ID that the API is ratelimiting in this response.