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 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}

LBots Panel

Bot Panels or "Dashboards" with us require some data from you to function best. After that, you can fetch our data.
For the "POST URL" you can provide in your dashboard editor, non-discord URLs will receive the field: value data similar to our API webhooks. Discord webhook URLs will receive a message

Warning: We will attempt to validate data over the browser, but no attempt is made once the data reaches the server. You should ensure each field contains data is what you are expecting. All data values are string unless BOOL or NULL.

Update Panel Guild Register

In order to filter guilds to mutuals with your bot while a user is visiting your panel, we request you give us an array of guild IDs.
If you:

  • Give us an ID not in our system, we will create space for it. (Your bot has joined a new server)
  • Give us an ID we already have, nothing will happen. (Your bot is still in that server)
  • Do not give us an ID we already have, it will be deleted. (Your bot left the server / was kicked)

POST /panel/<botid>/guilds
Params:
  - botid: The ID of your bot
Post Data:
  - guild_ids: An array of guild IDs to put into the system
  - guild_count: Optional, used purely for validation if provided. 
Responses:
  - 400: Invalid post data provided
  - 200: Update successful
  - 798: You broke it.
Ratelimits:
  - 2 per 20s

Post Data examples:

{guild_ids: [10293012930219, 10293021934021940, 09705902903950212]}
{guild_ids: [10293012930219], guild_count: 1}

Response Example:

{status_code:200, success:true}
{status_code:400, success:false, error:"guild_count does not match length of guild_ids"}

Get Guild-Specific Panel Settings

Fetches the settings of a guild that we have stored.

GET /panel/<botid>/guild/<guildid>
Params:
  - botid: The ID of your bot
  - guildid: The guild you want to fetch settings for.
Responses:
  - 200: Fetch successful, see JSON body
  - 404: No data for specified guild id
Response Data:
  - data: A JSON object with field_name: value that matches the field names supplied in the dashboard editor.
Ratelimits:
  - 10 per 5s

Response Example:

{status_code: 200, success: true, data: {prefix: "!", nsfw_enabled: false}} 
{status_code: 404, success: false, error: "No guild data found with given ID"}

Update Guild-Specific Panel Settings

Sets the value of settings data for a guild. Useful if a user alters the prefix through the bot and you want it to reflect the change on the dashboard.

POST /panel/<botid>/guild/<guildid>/update
Params:
  - botid: The ID of your bot
  - guildid: The guild you want to update settings for.
Post Data:
  - *: You can post any key with any value, provided that the key exists as a unique field name (you specify these in the editor) and that the type matches up (so you cant submit "steve" to a toggle input). See examples
Responses:
  - 200: Fetch successful, see JSON body
  - 400: Object keys do not match dashboard field names
Ratelimits:
  - 8 per 5s

Post Data Examples:

{prefix: "?", nsfw_enabled: false, steve_count: 12}
// Radio Buttons: You should have the data for what each option means as you set the option name in the editor.
{multi_choice: "option1"}

Response Examples:

{status_code:200, success:true}
{status_code:400, success:false, error: "Data does not match field names specified in the editor"}

Webhooks

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.
Example:
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 164.132.90.251 or include some form of authentication as a querystring parameter.

Questions

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

/search