Bots on Discord Bot API

Getting Started

To use the bot API you first need an API key. To get one go to the API Keys page under your username on the navbar. This key goes in the Authorization header of all API requests.

Bots should send all API requests to https://bots.ondiscord.xyz/bot-api/ with authentication. Ratelimits are used in all routes and appear in response headers.

If a request fails it will have a message field in the response body explaining the problem.

Guild Count

Updates a bot's guild count. Trying to update the guild count for a bot that is not approved will return a 404 Not Found error.

Endpoint: POST /bots/:id/guilds
Ratelimit: 2req / 4min / bot

Sample request:

POST https://bots.ondiscord.xyz/bot-api/bots/125367104336691200/guilds HTTP/1.1
Authorization: b1c678e8b0a346efe45e97c12b28f074
Content-Type: application/json

{
	"guildCount": 54783
}

Returns: 204 No Content

Check Review

Checks if a user has reviewed a bot. Returns a JSON response with the field exists, indicating if a review exists.

Endpoint: GET /bots/:id/review?owner={user id}
Ratelimit: 20req / 10s / bot

Sample request:

GET https://bots.ondiscord.xyz/bot-api/bots/125367104336691200/review?owner=437086154215391233 HTTP/1.1
Authorization: b1c678e8b0a346efe45e97c12b28f074

Returns:

{
	"exists": true
}

Commands

Updates a bot's commands.

Endpoint: POST /bots/:id/commands
Ratelimit: 10req / 1hr / bot

Defining Command Data

{
	// The sorting method for commands. null or 'default' will sort commands in categories by name alphabetically. 'none' will leave them in the order they are sent.
	// Command categories are not sorted, and are presented in the order of first-seen
	sort: 'default' | 'none' | null,
	// An array of command objects. If null then command data will be unset.
	// Currently there is a limit of 200 commands
	commands: [{
		// The name of the command
		name: String,
		// A description of the command, supporting limited markdown (**, *, `, links, lists, preserved newlines), and up to 1,000 characters in length
		description: String | null,
		// Options for the command. Args can either be a string (the arg name), or an object with more specifications.
		// There is a limit of 20 args per command
		args: [{
			// The arg name
			text: String,
			// The type of the argument
			type: 'required' | 'optional'
		}] | [String] | null,
		// Minimum wait time before the command can be used again
		cooldown: Number | null,
		// Units to append the the cooldown. By default 's' will be used
		cooldownUnit: 's' | 'm' | 'h' | 'd' | null,
		// Alternative names for the command.
		// There is a limit of 10 aliases per command
		aliases: [String] | null,
		// Examples of how to use the command.
		// There is a limit of 6 examples per command, with 200 characters each
		examples: [String] | null,
		// Permissions required to use the command. These do not have to be specific Discord permissions, any text is allowed.
		// There is a limit of 10 permissions per command
		permissions: [String] | null,
		// The category to show this command under. This exact text will be used for the category name
		category: String | null,
		// The prefix for this command. If no prefix is given then the prefix specified on the bot page will be used
		prefix: String | null
	}, ...]
}

Sample request:

POST https://bots.ondiscord.xyz/bot-api/bots/125367104336691200/commands HTTP/1.1
Authorization: b1c678e8b0a346efe45e97c12b28f074
Content-Type: application/json

{
	'sort': 'default',
	'commands': [{
		'name': 'anime',
		'description': 'Shows your information about an anime from [AniList](https://anilist.co)'
		'args': [{ 'text': 'name', 'type': 'required' }, 'options'],
		'cooldown': 5,
		'cooldownUnit': 'm',
		'aliases': ['ani'],
		'examples': [
			'!anime Toradora'
		],
		'permissions': ['Manage Channel'],
		'category': 'Anime Commands',
		'prefix': '!'
	}, ...]
}

Returns:
When invalid data is sent:
400 Bad Request

{
	"message": "Command arg types must be a string with the value \"required\" or \"optional\""
}

When successful:
204 No Content