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, ~v5)

Warning: this endpoint is deprecated since v5, consider using 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 (v5)

This API method replaces /roleChange.

Request (json object)

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

Response (application/json)

• status string
• meta may or may not be present to provide additional info
• role_changes - array of objects
  • user_id
  • role_id
  • 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
• invalid_user, HTTP 400 - user id is invalid or user is not in guild
• partial_success, HTTP 200 - some role changes applied successfully, but one or more couldn't because hierarchy error
• success, HTTP 200 - all role changes applied successfully

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
• hierarchy the bot could not add or remove the role because of hierarchy; the bot only has permission to modify roles below its own role.