API - NamelessMC/Nameless-Link GitHub Wiki

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