Server APIs

General

Although the SDK does not require you to have a backend, for those who do, there are a number of APIs that can be invoked server to server. How these calls are made and structured and authenticated is documented on our developer portal here: https://discord.com/developers/docs/reference

You'll need to use a "bot token" to authenticate these calls which can be found in the setting of the application you created above. And be sure the token is prefixed with Bot or it won't work!

Open API Spec

Discord publishes an Open API Spec at https://github.com/discord/discord-api-spec, and this can be used to generate a client in your preferred backend language to make it easier to call the various APIs. A good tool for that is https://openapi-generator.tech/

For Python for example that might look like this:

import openapi_client
import os
from pprint import pprint
 
configuration = openapi_client.Configuration(host = "https://discord.com/api/v10")
configuration.api_key['BotToken'] = 'Bot ' + os.environ["API_KEY"]
with openapi_client.ApiClient(configuration) as api_client:
    api_instance = openapi_client.DefaultApi(api_client)
 
    request = openapi_client.CreateLobbyRequest()
    request.metadata={'foo':'bar'}
    pprint(api_instance.create_lobby(request))

Lobbies

Create a lobby % POST /lobbies

Creates a new discordpp::LobbyHandle, adding any of the specified members to it if necessary. Clients will not be able to join or leave a lobby created using this API via the SDK functions (such as discordpp::Client::CreateOrJoinLobby). Returns the created Lobby object.

JSON Params

Field	Type	Description
metadata?	Dict<string, string>	An optional dictionary of string key/value pairs. The max total length is 1000.
members?	Array<LobbyMember>	An optional array of up to 25 users to be added to the lobby
idle_timeout_seconds?	integer	How long to wait before shutting down a lobby when it is idle. The value can be between 5 and 604800 (7 days). See discordpp::LobbyHandle for more details on this behavior.

LobbyMember JSON Params

Field	Type	Description
id	snowflake	The Discord user id of the user to add
metadata?	Dict<string, string>	An optional dictionary of string key/value pairs. The max total length is 1000.
flags?	integer	Currently the only supported flag is CanLinkLobby which is 1<<0

Edit a lobby with % PATCH /lobbies/<lobby_id>

Updates the lobby with the new fields, returns the updated Lobby object.

JSON Params

Field	Type	Description
metadata?	Dict<string, string>	An optional dictionary of string key/value pairs. The max total length is 1000. Overwrites any existing metadata.
members?	Array<LobbyMember>	An optional array of up to 25 users to replace the lobby members with. If provided, lobby members not in this list will be removed from the lobby.
idle_timeout_seconds?	integer	How long to wait before shutting down a lobby when it is idle. The value can be between 5 and 604800 (7 days). See discordpp::LobbyHandle for more details on this behavior.

Delete a lobby % DELETE /lobbies/<lobby_id>

Deletes the specified lobby if it exists. Returns nothing. Is safe to call even if the lobby is already deleted as well.

Get a lobby % GET /lobbies/<lobby_id>

Returns the Lobby object for the specified lobby if it exists.

Add a user to a lobby % PUT /lobbies/<lobby_id>/members/<user_id>

Adds the given user to the specified lobby. If called when the user is already a member of the lobby will update fields such as metadata on that user instead. Returns the LobbyMember object.

JSON Params

Field	Type	Description
metadata?	Dict<string, string>	An optional dictionary of string key/value pairs. The max total length is 1000.
flags?	integer	Currently the only supported flag is CanLinkLobby which is 1<<0

Remove a user from a lobby % DELETE /lobbies/<lobby_id>/members/<user_id>

Removes the given user from the specified lobby. Returns nothing. It is safe to call this even if the user is no longer a member of the lobby, but will fail if the lobby does not exist.

Lobby Rate Limits

These are the current rate limits that are configured, but if any of these are a problem please reach out and let us know and we can work with you on it!

• The APIs for creating, deleting, and retrieving lobbies are each limited to 500/10s for your application.
• The APIs for adding and removing members from a lobby are each limited to 5000/10s for your application.
• Additionally, Discord imposes a global rate limit of 50/s across all API endpoints for a single application. This can be raised for individual applications to 1200/s, and we’re willing to do that, so please make sure to reach out about that when you get closer to launching!
• Discord also has to protect against misbehaving bots, so be sure to respect API rate limit responses. If an IP address receives thousands of 429 error codes in a short period for example, it will get blocked at the cloudflare level.
• The API for sending a message is limited to 3000/2h per user.
• The API for creating or joining a lobby is limited to 10/60s per user.