API Documentation

Basics

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.

Authentication

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.

Responses

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.

Ratelimits

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.

Endpoints

Definitions

  • 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
Params:
  - botid: The ID of the bot whose token it is
Responses:
  - 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
Params:
  - 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)
Responses:
  - 400: Invalid post data provided
  - 200: Update successful
Ratelimits:
  - 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
Params:
  - botid: The ID of your bot
Responses:
  - 404: Bot does not exist (should not happen)
  - 200: Returned ok
Response Data:
  - favourites, favorites: Amount of favourites your bot has (int)
Ratelimits:
  - 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>
Params:
  - botid: The ID of your bot
  - userid: The ID of the user we are checking for
Responses:
  - 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 favourited 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}

Questions

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

/search