Bots

All API endpoints related to bots.
get
Bots
https://api.discordlist.space/v2/bots
Retrieves all bots in the database.
Request
Response
Request
Query Parameters
tags
optional
string
Comma-separated tag IDs
filters
optional
string
Comma-separated filters (allowed values: approved, safeAvatar)
query
optional
string
The search terms to look for in the username or short description
sortDirection
optional
string
The sort direction (allowed values: ascending, descending, default: descending)
sortBy
optional
string
The property to sort by (custom values: top, new, random, updated, name, id, rating, default: top) 
count
optional
number
The amount of bots to retrieve (default: 16, min: 1, max: 50)
page
optional
number
The page number (default: 1, min: 1)
Response
200: OK
{
    "success": true,
    "page": 1,
    "count": 1816,
    "countPerPage": 16,
    "pageCount": 114,
    "sortBy": "top",
    "sortDirection": "descending",
    "data": [
        {
            "username": "omarpg",
            "discriminator": "7525",
            "avatar": "3a3a2947838fc29e2588a078a6575492",
            "active": true,
            "shortDescription": "Start your journey to collect the most Pokémon badges! RPG your pokemon to become the best trainer!",
            "fullDescription": "As a pokemon trainer, you start in the Kanto region, where you can catch pokemon and nurture them to increase their levels. The goal is to get stronger every day, and be able to challenge the best trainers of each region, starting with mighty Brock and his rock-solid defense.\r\n\r\no!setup gets you started.\r\n\r\no!tutorial will show you the basics.\r\n\r\no!spinstop will get you pokeballs. You can spin the stop every 5 minutes.\r\n\r\no!player will show your current status.\r\n\r\no!wildmon will show you the pokemon that have spawned in the wild for your current region. Spawns will change every 40-60 minutes.\r\n\r\no!catch is what you need to get the pokemons!\r\n\r\no!mons will show you your current monster inventory. You can hold 10 at the beginning, but getting badges will also reward you with more inventory space.\r\n\r\nFor the complete list of commands go to [www.omarpg.com](https://www.omarpg.com/#/rpg)\r\n",
            "inviteURL": "https://discordapp.com/oauth2/authorize?client_id=555170415773745172&scope=bot&permissions=0",
            "supportServer": "4SDW8K2",
            "safeAvatar": true,
            "owner": {
                "username": "readonlychild",
                "discriminator": "2464",
                "avatar": "f4f15601f85ce0441df7ecdadb976d37",
                "shortDescription": "",
                "banned": true,
                "admin": false,
                "donator": false,
                "createdAt": 1620699900782,
                "updatedAt": 1620756966363,
                "id": "208659391417679872"
            },
            "serverCount": 1744,
            "vanity": null,
            "websiteURL": "https://www.omarpg.com/#/rpg",
            "tags": [
                {
                    "type": "bot",
                    "name": "Utility",
                    "id": "utility"
                },
                {
                    "type": "bot",
                    "name": "Leveling",
                    "id": "leveling"
                },
                {
                    "type": "bot",
                    "name": "Fun",
                    "id": "fun"
                }
            ],
            "languages": [
                {
                    "name": "Unknown/Other",
                    "bots": 1817,
                    "servers": 0,
                    "id": "other"
                }
            ],
            "prefix": "o!",
            "createdAt": 1587328048922,
            "updatedAt": 1620756966450,
            "upvoteCount": 244,
            "reviews": {
                "count": 0,
                "averageRating": 0
            },
            "secondaryOwners": [],
            "id": "555170415773745172"
        },
        ...
    ]
}
get
Bot
https://api.discordlist.space/v2/bots/:id
Retrieves a specific bot from the database.
Request
Response
Request
Path Parameters
id
required
string
 The ID of the bot
Response
200: OK
{
    "username": "omarpg",
    "discriminator": "7525",
    "avatar": "3a3a2947838fc29e2588a078a6575492",
    "active": true,
    "shortDescription": "Start your journey to collect the most Pokémon badges! RPG your pokemon to become the best trainer!",
    "fullDescription": "As a pokemon trainer, you start in the Kanto region, where you can catch pokemon and nurture them to increase their levels. The goal is to get stronger every day, and be able to challenge the best trainers of each region, starting with mighty Brock and his rock-solid defense.\r\n\r\no!setup gets you started.\r\n\r\no!tutorial will show you the basics.\r\n\r\no!spinstop will get you pokeballs. You can spin the stop every 5 minutes.\r\n\r\no!player will show your current status.\r\n\r\no!wildmon will show you the pokemon that have spawned in the wild for your current region. Spawns will change every 40-60 minutes.\r\n\r\no!catch is what you need to get the pokemons!\r\n\r\no!mons will show you your current monster inventory. You can hold 10 at the beginning, but getting badges will also reward you with more inventory space.\r\n\r\nFor the complete list of commands go to [www.omarpg.com](https://www.omarpg.com/#/rpg)\r\n",
    "inviteURL": "https://discordapp.com/oauth2/authorize?client_id=555170415773745172&scope=bot&permissions=0",
    "supportServer": "4SDW8K2",
    "safeAvatar": true,
    "owner": {
        "username": "readonlychild",
        "discriminator": "2464",
        "avatar": "f4f15601f85ce0441df7ecdadb976d37",
        "shortDescription": "",
        "banned": true,
        "admin": false,
        "donator": false,
        "createdAt": 1620699900782,
        "updatedAt": 1620756966363,
        "id": "208659391417679872"
    },
    "serverCount": 1744,
    "vanity": null,
    "websiteURL": "https://www.omarpg.com/#/rpg",
    "tags": [
        {
            "type": "bot",
            "name": "Utility",
            "id": "utility"
        },
        {
            "type": "bot",
            "name": "Leveling",
            "id": "leveling"
        },
        {
            "type": "bot",
            "name": "Fun",
            "id": "fun"
        }
    ],
    "languages": [
        {
            "name": "Unknown/Other",
            "bots": 1817,
            "servers": 0,
            "id": "other"
        }
    ],
    "prefix": "o!",
    "createdAt": 1587328048922,
    "updatedAt": 1620756966450,
    "upvoteCount": 244,
    "reviews": {
        "count": 0,
        "averageRating": 0
    },
    "secondaryOwners": [],
    "id": "555170415773745172"
}
404: Not Found
{
    "errors": [
        "Not Found"
    ]
}
post
Update Bot
https://api.discordlist.space/v2/bots/:id
Changes details of the bot listing.
Request
Response
Request
Path Parameters
id
required
string
The ID of the bot
Headers
Content-Type
required
string
Required to be application/json
Authorization
required
string
The bot token or user token
Body Parameters
serverCount
optional
number
The server count of the bot (null to unset, min: 0)
active
optional
boolean
Changes whether the listing is active or not
websiteURL
optional
string
The website URL (protocol: http or https, min: 1)
vanity
optional
string
Vanity code (only available to donators, min: 1, max: 24)
languages
optional
array
An array of language IDs (min: 1, max: 12)
tags
optional
array
An array of tag IDs (min: 1, max: 7)
supportServer
optional
string
The support server invite code
safeAvatar
optional
boolean
Sets whether the bot avatar is appropriate
prefix
optional
string
The bot prefix (min: 1, max: 16)
inviteURL
optional
string
The listing invite URL (must match Discord auth URL, min: 1)
fullDescription
optional
string
The listing full description (min: 0, max: 20000)
shortDescription
optional
string
The listing short description (min: 1, max: 240)
Response
200: OK
{
    "success": true
}
get
Bot Reviews
https://api.discordlist.space/v2/bots/:id/reviews
Retrieves the reviews of a bot.
Request
Response
Request
Path Parameters
id
required
string
The ID of the bot
Query Parameters
sortDirection
optional
string
The sort direction (allowed values: ascending, descending, default: descending)
sortBy
optional
string
The property to sort by (default: top)
count
optional
number
The amount of reviews to retrieve (default: 16, min: 1, max: 50)
page
optional
number
The page number (default: 1, min: 1)
Response
200: OK
{
    "page": 1,
    "count": 1,
    "countPerPage": 16,
    "pageCount": 1,
    "sortBy": "top",
    "sortDirection": "descending",
    "data": {
        "averageRating": 5,
        "reviews": [
            {
                "user": {
                    "username": "PassTheMayo",
                    "discriminator": "8620",
                    "avatar": "8d7b060b71b4a904a965ef89c9a9bff7",
                    "shortDescription": "",
                    "banned": false,
                    "admin": true,
                    "donator": true,
                    "createdAt": 1620699881208,
                    "updatedAt": 1620756966254,
                    "id": "507329700402561045"
                },
                "title": "Great Bot",
                "comment": "This is my review of the bot.",
                "rating": 5,
                "upvotes": 0,
                "createdAt": 1620761916666,
                "upvoted": false,
                "id": "f4ae93cbb6284ba8492f9b24892503b3e9282701d6285a78"
            }
        ]
    }
}
get
Bot Analytics
https://api.discordlist.space/v2/bots/:id/analytics
Retrieves analytics on a bot.
Request
Response
Request
Path Parameters
id
required
string
The ID of the bot
Headers
Authorization
required
string
The bot or user token
Query Parameters
to
optional
number
The timestamp to end the data at (default: now) 
from
optional
number
The timestamp to start the data from (default: 7 days ago)
Response
200: OK
{
    "from": 1620237196926,
    "to": 1620841996926,
    "count": 23,
    "data": [
        {
            "timestamp": 1620752400000,
            "impressions": 0,
            "invites": 0,
            "upvotes": 0,
            "views": 2,
            "id": "379e292bbc78b28a3d6782508745f24cdbda4dc18357657c51b135fbdb5f335b",
            "locationStatistics": [],
            "referralStatistics": [
                {
                    "source": null, // 'null' source means direct link
                    "views": 2
                }
            ]
        },
        ...
    ]
}
get
Bot Upvotes
https://api.discordlist.space/v2/bots/:id/upvotes
Returns everyone who has upvoted the bot in the month.
Request
Response
Request
Path Parameters
id
required
string
The ID of the bot
Headers
Authorization
required
string
The bot token or user token
Query Parameters
sortDirection
optional
string
The sort direction (allowed values: ascending, descending, default: ascending)
sortBy
optional
string
The property to sort by (default: timestamp)
count
optional
number
The amount of upvotes to retrieve (default: 16, min: 1, max: 50)
page
optional
number
The page number (default: 1, min: 1)
Response
200: OK
[ // ??Array<Object>
    {
        "user": {
            "id": "507329700402561045", // String
            "username": "PassTheMayo", // String
            "discriminator": "1281", // String
            "avatar": "6c1dbec73fd887f0b2e6f29e4e9091a6", // String
            "short_description": "..." // ?String
        },
        "timestamp": 1546208945017 // Number
    },
    ...
]
401: Unauthorized
{
    "success": false, // Boolean
    "code": 401, // Number
    "message": "Missing Authorization header" // String
}
403: Forbidden
{
    "success": false, // Boolean
    "code": 403, // Number
    "message": "The provided authorization does not match the requested bot's token" // String
}
404: Not Found
{
    "success": false, // Boolean
    "code": 404, // Number
    "message": "Bot not found" // String
} 
get
Bot User Upvote Status
https://api.discordlist.space/v2/bots/:id/status/:userID
Checks if a specific user has upvoted the bot.
Request
Response
Request
Path Parameters
userID
required
string
The ID of the user
id
required
string
The ID of the bot
Headers
Authorization
required
string
The bot or user token
Response
200: OK
{
    "upvoted": true,
    "timestamp": 1621796740255
}
get
Bot Upvote Leaderboard
https://api.discordlist.space/v2/bots/:id/upvotes/leaderboard
Gets the top upvoters of this month.
Request
Response
Request
Path Parameters
id
required
string
The ID of the bot
Query Parameters
sortDirection
optional
string
The sort direction (allowed values: ascending, descending, default: descending)
sortBy
optional
string
The property to sort by (default: count)
count
optional
number
The amount of users to retrieve (min: 1, max: 50, default: 16)
page
optional
number
The page number (min: 1, default: 1)
Response
200: OK
{
    "page": 1,
    "count": 1,
    "countPerPage": 16,
    "pageCount": 1,
    "sortBy": "count",
    "sortDirection": "descending",
    "data": [
        {
            "count": 1,
            "user": {
                "username": "PassTheMayo",
                "discriminator": "8620",
                "avatar": "8d7b060b71b4a904a965ef89c9a9bff7",
                "shortDescription": "",
                "banned": false,
                "admin": true,
                "donator": true,
                "createdAt": 1621740577129,
                "updatedAt": 1621796515571,
                "id": "507329700402561045"
            },
            "id": "507329700402561045"
        }
    ]
}
get
Bot Audit Log
https://api.discordlist.space/v2/bots/:id/audit
Retrieves the bot listing audit log.
Request
Response
Request
Path Parameters
id
required
string
The ID of the bot
Headers
Authorization
required
string
The bot or user token
Query Parameters
page
optional
number
The page number (min: 1, default: 1)
count
optional
number
The amount of logs to retrieve (min: 1, max: 50, default: 16)
sortBy
optional
string
The property to sort by (default: timestamp)
sortDirection
optional
string
The sort direction (allowed values: ascending, descending, default: descending)
Response
200: OK
​
get
Bot Owners
https://api.discordlist.space/v2/bots/:id/owners
Gets the owners of the bot listing.
Request
Response
Request
Path Parameters
id
required
string
The ID of the bot
Query Parameters
page
optional
number
The page number (min: 1, default: 1)
count
optional
number
The amount of owners to retrieve (min: 1, max: 50, default: 16)
sortBy
optional
string
The property to sort by (default: id)
sortDirection
optional
string
The sort direction (allowed valued: ascending, descending, default: ascending)
Response
200: OK
​