API Documentation

Getting Started

You will need to get an API key from your bot page by logging in and clicking "Get API Key"

All API requests should be sent to https://api.discordbots.co

Guild & Shard Count

This allows you to post to our API to update the Server Count and Shard Count on your bot page.

Endpoint: /v1/public/bot/:id/stats

Method: POST

Rate Limit: 1 Request / 5 minutes

URL Parameters:

:id | Your Bot ID

Headers:

Authorization: Your API Key

Content-Type: application/json

Body:

serverCount | number

shardCount | number

Success:

Status Code: 200

Return: { error: false, response: 'Posted your stats successfully.' }

Error:

Status Code: 400 | 404 | 429

Return: { error: true, response: 'You are being rate limited.' }

View Current Bot Information

This allows you to get most of the information about your bot.

Endpoint: /v1/public/bot/:id

Method: GET

Headers:

Authorization: Your API Key

Success:

Status Code: 200

Return: { error: false, response: {Response} }

Response:

id | string

owners | string[]

votes | number

prefix | string

library | string

tags | string[]

description | string

overview | string

discordInvite | string | null

website | string | null

certified | boolean

promoted | boolean

vanity | string | null

github | string | null

donateUrl | string | null

serverCount | number | null

shardCount | number | null

Error:

Status Code: 404

Return: { error: true, response: 'API key does not match a bot.' }

View Current Bot Reviews

This allows you to get the reviews submitted about your bot.

Endpoint: /v1/public/bot/:id/reviews

Method: GET

Headers:

Authorization: Your API Key

Success:

Status Code: 200

Return: { error: false, response: {Response[]} }

Response:

id | string

botId | string

reviewerId | string

positive | boolean

review | string

reply | string

Error:

Status Code: 404

Return: { error: true, response: 'API key does not match a bot.' }

Webhook Documentation

Getting Started

You will need to get a webhook token from your bot page by logging in and clicking "Get Webhook Token" - this is not required but will be useful for validating incoming requests to your webhook URL.

You will also need to edit your bot and provide an already set up webhook URL.

Voting Hook

You will receive a POST request when a user votes for your bot.

Headers:

Authorization: Your Webhook Token

Content-Type: application/json

Body:

userId | string

test | boolean

type | "vote"

Review Hook

You will receive a POST request when a user submits a review on your bot.

Headers:

Authorization: Your Webhook Token

Content-Type: application/json

Body:

userId | string

content | string

positive | boolean

test | boolean

type | "review"