API Documentation


The base URL for the API is https://lbots.org/api/v1, so make sure that if your requests are returning a 404 you're using the current API version (currently v1). In the event of calling a deprecated endpoint, it will return error: DEPRECATED as part of the JSON response. If you're not authenticated properly, you'll receive a 401 Unauthorized, and if you reach a ratelimit you'll receive a 429 Too Many Requests instead. Additional data may be sent along with such responses but should not be relied upon.


If you want to use the API, you'll first need a key to authenticate your requests with. You should send the key with the Authorization header in all requests, and for any POSTs you do, be sure to set Content-Type: application/json and pass valid JSON as the data.


All responses from the API will return a JSON body, containing the status_code of the response and whether the request was completed or not in the success field. If it's false, an additional field error will be provided containing slightly more information than the error code.


If you are own a large bot and find that any of the ratelimits are simply insufficient, please contact a member of staff so we can add your IPs to the whitelist. If your bot is not large, please reconsider at what points you need to make an API call. We have chosen each ratelimit based on how much we expect it to be used at a maximum in a bot of ~50k servers.



  • Params: The parameters that will be different for each person and use case. They are passed as part of the URL.
  • Post Data: The different data keys that are accepted in the JSON data you should be sending. Be sure to set Content-Type: application/json
  • Responses: The possible response codes you might receive and what the problem would be.
  • Response Data: The keys that will be returned in the JSON response after your request. Generic data types are provided in brackets.
  • Ratelimits: The amount of requests per X amount of time you can make to this endpoint before being denied access.
  • * denotes a required piece of data in a request.

Invalidate Token

Invalidates the current token used for authentication and creates a new one. Useful if someone accidentally leaks their token and the owner isn't around to regenerate it manually. It can then be re-fetched from the bot's page. The token that will be invalidated is whatever is used to authenticate.

GET /bots/<botid>/invalidate
  - botid: The ID of the bot whose token it is
  - 200: Invalidation success

Response Example:

{status_code:200, success:true}

Bot Statistics

Update the statistics of your bot, which is displayed on your bot page pump them numbersTM.

POST /bots/<botid>/stats
  - botid: The ID of your bot
Post Data:
  - guild_count*: Number of servers your bot / shard is in (int)
  - shard_id: The ID of the shard that contains the guild_count (int)
  - shard_count: The total number of shards your bot is running (int)
  - 400: Invalid post data provided
  - 200: Update successful
  - 20 per 5s

Post Data examples:

{guild_count: 893}
{guild_count: 19902, shard_count: 19}
{guild_count: 564, shard_count: 4, shard_id: 2}

Response Example:

{status_code:200, success:true}

If you pass a shard_id, it is expected to be numerical and will store the amount of guilds that shard can see. If your bot posts sharded data, we will then display the sum of all shards that post.

Bot Favourites

Fetch the total amount of favourites your bot has in this quarter.

GET /bots/<botid>/favourites
GET /bots/<botid>/favorites
  - botid: The ID of your bot
  - 404: Bot does not exist (should not happen)
  - 200: Returned ok
Response Data:
  - favourites, favorites: Amount of favourites your bot has (int)
  - 3 per 4s

Response Example:

{status_code:200, success:true, favourites:30, favorites:30}

Bot Has User Favourited

Check if a given user has favourited your bot at any point in the current quarter.

GET /bots/<botid>/favourites/user/<userid>
GET /bots/<botid>/favorites/user/<userid>
  - botid: The ID of your bot
  - userid: The ID of the user we are checking for
  - 200: Returned ok
Response Data:
  - user: The user's ID (int)
  - time: The time the user favourited the bot, if applicable (datetime|null)
  - favourited, favorited: If the user add or removed their favourite for the bot (bool)

Response Examples:

{status_code:200, success:true, userid:367330084337745920, time:"Mon, 21 Jan 2019 01:19:38 GMT", favourited: true, favorited:true}
{status_code:200, success:true, userid:367330084337745920, time:null, favourited: false, favorited:false}


As oppose to requesting the API, LBots can send a POST of the favourite data to a URL. You can set your URL and Webhook Type on your bot's edit page. The only difference in the response that should be noted is that status_code and success will not be included.

Discord Webhook

Make your Discord webhook and enter that webhook URL as the URL for us to send data to. The corresponding channel will receive a message containing the same JSON response the API provides. It is up to you to decode this and do with data as you please.
alt text

LBots API Webhook

The data sent will be of type application/json and the body will be the same raw JSON provided by the Has-User-Favourited API route (same as above screenshot). This should be used if you wish to receive the data on your own webserver. To prevent abuse, we ask you whitelist our only IP address or include some form of authentication as a querystring parameter.


Any questions should be directed straight into the nearest bin to our support server where there are many talented and knowledgeable developers.