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, consider using applyRoleChanges instead

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 from earlier versions. The old endpoint is still available for backwards compatibility.

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.