{"openapi":"3.1.0","info":{"contact":{"email":"lurkr@almeidx.dev","name":"Almeida","url":"https://almeidx.dev"},"description":"Specification for the Lurkr API","termsOfService":"https://lurkr.gg/terms","title":"Lurkr API","version":"2"},"components":{"headers":{"retry-after":{"description":"If the max has been reached, the seconds the client must wait before they can make new requests","required":false},"x-ratelimit-limit":{"description":"How many requests the client can make","required":true},"x-ratelimit-remaining":{"description":"How many requests remain to the client in the time window","required":true},"x-ratelimit-reset":{"description":"How many seconds must pass before the rate limit resets","required":true}},"responses":{"4xx":{"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string"}}}}},"description":"Client error"},"5xx":{"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string"}}}}},"description":"Server error"}},"securitySchemes":{"apiKey":{"description":"The user's API key to authenticate requests","in":"header","name":"X-Api-Key","type":"apiKey"}},"schemas":{}},"paths":{"/guilds/{guildId}/role-rewards/level":{"get":{"summary":"Get the role rewards changes for a specific level","tags":["guilds"],"parameters":[{"schema":{"type":"integer","maximum":10000,"minimum":0},"in":"query","name":"level","required":true,"description":"The new level of the user"},{"schema":{"type":"string","maxLength":19,"minLength":17,"pattern":"^[1-9]\\d+$","title":"Snowflake"},"in":"query","name":"userId","required":true,"description":"A Discord snowflake identifier. Currently, this is not used but may be in the future"},{"schema":{"type":"string","maxLength":19,"minLength":17,"pattern":"^[1-9]\\d+$","title":"Snowflake"},"in":"path","name":"guildId","required":true,"description":"A Discord snowflake identifier"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["addRoles","removeRoles"],"properties":{"addRoles":{"type":"array","items":{"type":"string","description":"A Discord snowflake identifier","maxLength":19,"minLength":17,"pattern":"^[1-9]\\d+$","title":"Snowflake"},"description":"The roles that the user should be given. This does not currently take into account the roles the user has"},"removeRoles":{"type":"array","items":{"type":"string","description":"A Discord snowflake identifier","maxLength":19,"minLength":17,"pattern":"^[1-9]\\d+$","title":"Snowflake"},"description":"The roles that the user should be removed from. This does not currently take into account the roles the user has"}}}}}},"404":{"description":"Guild not found","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string"}},"description":"Guild not found"}}}}}}},"/levels/{entry}":{"get":{"summary":"Get Leaderboard","tags":["levels"],"description":"Returns the leaderboard for a guild. This endpoint is paginated and returns up to 100 results per call.","parameters":[{"schema":{"type":"integer","minimum":1},"in":"query","name":"page","required":true},{"schema":{"anyOf":[{"type":"string","description":"A Discord snowflake identifier","maxLength":19,"minLength":17,"pattern":"^[1-9]\\d+$","title":"Snowflake"},{"type":"string","pattern":"^[\\da-zA-Z]+$"}]},"in":"path","name":"entry","required":true,"description":"Guild ID or leaderboard vanity"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["guild","isManager","levels","multipliers","roleRewards","vanity","xpGainInterval","xpGlobalMultiplier","xpPerMessageMax","xpPerMessageMin"],"properties":{"guild":{"type":"object","required":["icon","id","memberCount","name"],"properties":{"icon":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The guild icon hash, if it has one"},"id":{"type":"string","description":"A Discord snowflake identifier","maxLength":19,"minLength":17,"pattern":"^[1-9]\\d+$","title":"Snowflake"},"memberCount":{"type":"integer","minimum":1},"name":{"type":"string"}}},"isManager":{"type":"boolean"},"levels":{"type":"array","items":{"type":"object","required":["level","messageCount","nextLevelXp","progress","rank","user","userId","xp"],"properties":{"level":{"type":"integer","minimum":0},"messageCount":{"type":"integer","minimum":0},"nextLevelXp":{"type":"integer","minimum":0},"progress":{"type":"number","maximum":100,"minimum":0},"rank":{"type":"integer","minimum":1},"user":{"allOf":[{"type":"object","required":["accentColour"],"properties":{"accentColour":{"anyOf":[{"type":"string"},{"type":"null"}]}}},{"type":"object","required":["avatar","discriminator","globalName","username"],"properties":{"avatar":{"anyOf":[{"type":"string","maxLength":34,"minLength":32,"pattern":"^(?:a_)?[a-z0-9]{32}$"},{"type":"null"}],"description":"The avatar hash of the user, if they have one"},"discriminator":{"type":"string"},"globalName":{"anyOf":[{"type":"string"},{"type":"null"}]},"username":{"type":"string"}},"description":"This data might not always be up to date","title":"User"}]},"userId":{"type":"string","description":"A Discord snowflake identifier","maxLength":19,"minLength":17,"pattern":"^[1-9]\\d+$","title":"Snowflake"},"xp":{"type":"integer","minimum":0}}}},"multipliers":{"type":"array","items":{"type":"object","required":["id","multiplier","targets","type"],"properties":{"id":{"type":"string","format":"uuid"},"multiplier":{"type":"number","maximum":5,"minimum":0},"targets":{"type":"array","items":{"anyOf":[{"type":"object","required":["color","id","name","position"],"properties":{"color":{"anyOf":[{"type":"integer"},{"type":"null"}]},"id":{"type":"string","description":"A Discord snowflake identifier","maxLength":19,"minLength":17,"pattern":"^[1-9]\\d+$","title":"Snowflake"},"name":{"type":"string"},"position":{"type":"integer","minimum":0}},"title":"Role"},{"type":"object","required":["id","name","parentId","position","type"],"properties":{"id":{"type":"string","description":"A Discord snowflake identifier","maxLength":19,"minLength":17,"pattern":"^[1-9]\\d+$","title":"Snowflake"},"name":{"type":"string"},"parentId":{"anyOf":[{"type":"string","description":"A Discord snowflake identifier","maxLength":19,"minLength":17,"pattern":"^[1-9]\\d+$","title":"Snowflake"},{"type":"null"}]},"position":{"type":"integer","minimum":0},"type":{"type":"integer","minimum":0}},"title":"Channel"}]},"description":"The multiplier type dictates the target type"},"type":{"enum":["Channel","Role"]}}}},"roleRewards":{"type":"array","items":{"type":"object","required":["id","level","roles"],"properties":{"id":{"type":"string","format":"uuid"},"level":{"type":"integer","minimum":0},"roles":{"type":"array","items":{"type":"object","required":["color","id","name","position"],"properties":{"color":{"anyOf":[{"type":"integer"},{"type":"null"}]},"id":{"type":"string","description":"A Discord snowflake identifier","maxLength":19,"minLength":17,"pattern":"^[1-9]\\d+$","title":"Snowflake"},"name":{"type":"string"},"position":{"type":"integer","minimum":0}},"title":"Role"}}}}},"vanity":{"anyOf":[{"type":"string","maxLength":32,"minLength":2,"pattern":"^[\\da-z]+$"},{"type":"null"}]},"xpGainInterval":{"type":"integer","description":"The cooldown period for XP gain in seconds","maximum":86400000,"minimum":10000},"xpGlobalMultiplier":{"type":"number","maximum":5,"minimum":0},"xpPerMessageMax":{"type":"integer","description":"Maximum XP to gain per message","maximum":1000,"minimum":1},"xpPerMessageMin":{"type":"integer","description":"Minimum XP to gain per message","maximum":1000,"minimum":1}}}}}},"401":{"description":"This leaderboard is not public. You need to be authenticated to view it.","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string"}},"description":"This leaderboard is not public. You need to be authenticated to view it."}}}},"403":{"description":"This leaderboard is not public. You do not have sufficient permissions to view it.","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string"}},"description":"This leaderboard is not public. You do not have sufficient permissions to view it."}}}},"404":{"description":"The guild was not found or does not have the leveling system enabled.","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string"}},"description":"The guild was not found or does not have the leveling system enabled."}}}}}}},"/levels/{guildId}/users/{userId}":{"get":{"summary":"Get User Level","tags":["levels"],"description":"Get a user's level data in a guild","parameters":[{"schema":{"type":"string","maxLength":19,"minLength":17,"pattern":"^[1-9]\\d+$","title":"Snowflake"},"in":"path","name":"guildId","required":true,"description":"A Discord snowflake identifier"},{"schema":{"type":"string","maxLength":19,"minLength":17,"pattern":"^[1-9]\\d+$","title":"Snowflake"},"in":"path","name":"userId","required":true,"description":"A Discord snowflake identifier"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["level","user"],"properties":{"level":{"type":"object","required":["lastUpdated","level","messageCount","rank","xp"],"properties":{"lastUpdated":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"level":{"type":"integer","maximum":10000,"minimum":0},"messageCount":{"type":"integer","minimum":0},"rank":{"type":"integer","minimum":1},"xp":{"type":"integer","maximum":2147483647,"minimum":0}}},"user":{"type":"object","required":["avatar","discriminator","globalName","username"],"properties":{"avatar":{"anyOf":[{"type":"string","maxLength":34,"minLength":32,"pattern":"^(?:a_)?[a-z0-9]{32}$"},{"type":"null"}],"description":"The avatar hash of the user, if they have one"},"discriminator":{"type":"string"},"globalName":{"anyOf":[{"type":"string"},{"type":"null"}]},"username":{"type":"string"}},"description":"This data might not always be up to date","title":"User"}}}}}}}},"post":{"summary":"Create User Level","tags":["levels"],"description":"Create a new user level entry in a guild","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["user","xp"],"properties":{"user":{"allOf":[{"type":"object","required":["avatar","discriminator","username"],"properties":{"avatar":{"anyOf":[{"type":"string","maxLength":34,"minLength":32,"pattern":"^(?:a_)?[a-z0-9]{32}$"},{"type":"null"}],"description":"The avatar hash of the user, if they have one"},"discriminator":{"type":"string"},"username":{"type":"string"}}},{"type":"object","properties":{"globalName":{"anyOf":[{"type":"string"},{"type":"null"}]}}}]},"xp":{"type":"integer","maximum":2147483647,"minimum":0}}}}}},"parameters":[{"schema":{"type":"string","maxLength":19,"minLength":17,"pattern":"^[1-9]\\d+$","title":"Snowflake"},"in":"path","name":"guildId","required":true,"description":"A Discord snowflake identifier"},{"schema":{"type":"string","maxLength":19,"minLength":17,"pattern":"^[1-9]\\d+$","title":"Snowflake"},"in":"path","name":"userId","required":true,"description":"A Discord snowflake identifier"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["level"],"properties":{"level":{"type":"object","required":["level","messageCount","xp"],"properties":{"level":{"type":"integer","maximum":10000,"minimum":0},"messageCount":{"type":"integer","minimum":0},"xp":{"type":"integer","maximum":2147483647,"minimum":0}}}}}}}}}},"delete":{"summary":"Delete User Level","tags":["levels"],"description":"Delete a user's level from a guild","parameters":[{"schema":{"type":"string","maxLength":19,"minLength":17,"pattern":"^[1-9]\\d+$","title":"Snowflake"},"in":"path","name":"guildId","required":true,"description":"A Discord snowflake identifier"},{"schema":{"type":"string","maxLength":19,"minLength":17,"pattern":"^[1-9]\\d+$","title":"Snowflake"},"in":"path","name":"userId","required":true,"description":"A Discord snowflake identifier"}],"security":[{"apiKey":[]}],"responses":{"204":{"description":"User level deleted successfully"}}},"patch":{"summary":"Update User Level","tags":["levels"],"description":"Update the experience of a user in a guild","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["xp"],"properties":{"triggerCooldown":{"type":"boolean","default":false,"description":"Whether to trigger the leveling cooldown for this user, meaning they won't gain XP for the duration of the cooldown after this request"},"xp":{"anyOf":[{"type":"object","required":["increment"],"properties":{"increment":{"type":"integer","maximum":2147483647,"minimum":1}}},{"type":"object","required":["decrement"],"properties":{"decrement":{"type":"integer","maximum":2147483647,"minimum":1}}},{"type":"integer","maximum":2147483647,"minimum":0}],"description":"The amount to modify the user's XP by. We recommend using the atomic increment/decrement methods, if possible."}}}}}},"parameters":[{"schema":{"type":"string","maxLength":19,"minLength":17,"pattern":"^[1-9]\\d+$","title":"Snowflake"},"in":"path","name":"guildId","required":true,"description":"A Discord snowflake identifier"},{"schema":{"type":"string","maxLength":19,"minLength":17,"pattern":"^[1-9]\\d+$","title":"Snowflake"},"in":"path","name":"userId","required":true,"description":"A Discord snowflake identifier"}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["level"],"properties":{"level":{"type":"object","required":["level","messageCount","xp"],"properties":{"level":{"type":"integer","maximum":10000,"minimum":0},"messageCount":{"type":"integer","minimum":0},"xp":{"type":"integer","maximum":2147483647,"minimum":0}}}}}}}}}}}},"servers":[{"description":"Production server","url":"https://api.lurkr.gg/v2"}],"tags":[{"name":"levels"}]}