API

GET /status (v1.0, v1.1, v1.2, v2.0, v3, v4, v5)

Response (/text/plain)

success

(no newline)

POST /roleChange (v1.0, v1.1, v1.2)

warning: this description is for old versions, please read on for the newer endpoint description

request (json object):

• guild_id - Discord guild id
• user_id - Discord user id
• api_key - Website API key
• remove_role_id - Id of role to add to this user
• add_role_id - Id of role to remove from this user

responses:

• badparameter - Missing or invalid parameter, see above
• error - Bot internal error, not the API caller's fault
• invguild - Guild does not exist or bot is not in guild
• invuser - User does not exist or is not in specified guild
• notlinked - Bot is not linked to website for this guild
• unauthorized - Invalid API key
• invrole
• hierarchy - Just a warning, not an error. Means that the bot could not add/remove roles because they are higher than the bot role. If multiple roles are specified (add and remove) the other may have been changed successfully.
• success

POST /roleChange (v2, v3, v4)

Warning: this endpoint is deprecated, use applyRoleChanges instead. Due to excessive load, the official bot ignores roleChange requests by always responding with fullsuccess without doing anything.

Request (json object):

• guild_id - Discord guild id
• user_id - Discord user id
• api_key - Website API key
• roles - array of objects
  • id - role id
  • action - 'add' or 'remove'

Responses:

• badparameter - Missing or invalid parameter, see above
• error - Bot internal error, not the API caller's fault
• invguild - Guild does not exist or bot is not in guild
• invuser - User does not exist or is not in specified guild
• notlinked - Bot is not linked to website for this guild
• unauthorized - Invalid API key
• partsuccess - Just a warning, not an error. Means that the bot could not add/remove some roles because they are higher than the bot role or the role id is invalid. If multiple roles are specified, others may have been changed successfully.
• fullsuccess - All roles have been added/removed successfully

POST /applyRoleChanges (v4 since 2022-11-08, v5)

This API method replaces /roleChange.

Request (json object)

• guild_id - Discord guild id string
• api_key - Website API key
• role_changes - Array of objects
  • user_id - Discord user id string
  • role_id - Discord role id string
  • action - string 'add' or 'remove'

Response (application/json)

• status string
• meta may or may not be present to provide additional info. Only meant for developers, do not display this to end users (except for log files etc)
• role_changes - array of objects
  • user_id string
  • role_id string
  • status - see below

Possible status responses:

• bad_request, HTTP 400 - Missing or invalid parameter
• not_linked, HTTP 400
• unauthorized, HTTP 401 - Invalid API key
• invalid_guild, HTTP 400 - guild id is invalid or bot is not in guild
• success, HTTP 200 - NOTE some roles changes may not have been applied successfully, also check status for every role change!

Possible role_changes->status responses:

• none the role was already added or was already removed, no action was needed
• added the role was added
• removed the role was removed
• no_permission the bot could not add or remove the role because of role hierarchy; the bot only has permission to modify roles below its own role.
• invalid_user user id is invalid or user is not member of guild
• invalid_role role id is invalid

POST /sendDirectMessage (v5 since 2024-06-08)

Request (json object):

• guild_id number
• user_id number
• api_key string
• message string