You can create an API instance without directly providing an access_token by using API.createAsync!
+Please use the API's createAsync method instead of the default constructor if you don't have at least an access_token!
+
Please use API.createAsync instead of the default constructor if you don't have at least an API.access_token!
An API object without an access_token is pretty much useless!
Optional access_The token used in basically all requests!
-Optional client?: { The details of your application client, necessary for using the refresh_token
-Optional expires?: DateThe expiration date of your access_token (doesn't affect application behaviour)
-Optional refresh_If a 401 error is gotten from the server while it has a refresh token, should it use it and try the request again? (defaults to true)
-Optional refresh_Should the application schedule a task to silently refresh the token right before the access_token expires? (defaults to true)
-Optional refresh_The token used to update your access_token and your refresh_token
-Optional scopes?: Scope[]The scopes your application have, assuming it acts as a user (doesn't affect application behaviour)
-Optional server?: stringThe URL of the API server the package contacts
-Optional timeout?: numberHow many seconds maximum should a request take, if there should be a maximum? (defaults to 20)
-Optional token_Should always be "Bearer"
-Optional user?: numberThe id of the user this application acts as, if any (doesn't affect application behaviour)
-Optional verbose?: "all" | "none" | "errors"How much stuff should the package log (defaults to none)
-The expiration date of your access_token
-If true, upon failing a request due to a 401, it will use the refresh_token and retry the request
If true, the application will silently use the refresh_token right before the access_token expires, as determined by expires
Optional refresh_Valid for an unknown amount of time, allows you to get a new token without going through the Authorization Code Grant!
-Use the API's refreshToken function to do that
Optional scopesThe scopes your application have, assuming it acts as a user
-The base url of the server where the requests should land (defaults to https://osu.ppy.sh)
+Private _expiresPrivate _refresh_Private Optional _refresh_Private Optional _refresh_The key that allows you to talk with the API
+If true, upon failing a request due to a 401, it will use the API.refresh_token if it exists (defaults to true)
+Configure how this instance should behave when it comes to automatically retrying a request
+In seconds, how long should it wait until retrying? (defaults to 2)
+If true, doesn't retry under any circumstances (defaults to false)
+How many retries maximum before throwing an APIError (defaults to 5)
+Should it retry a request upon successfully refreshing the token due to API.refresh_on_401 being true? (defaults to true)
Upon failing a request and receiving a response, because of which received status code should the request be retried? (defaults to [429])
+Should it retry a request if that request failed because it has been aborted by the API.timeout? (defaults to false)
+Optional scopesThe Scopes your application has, assuming it acts as a user
+The base url of the server where the requests should land (defaults to https://osu.ppy.sh)
For tokens, requests will be sent to the oauth/token route, other requests will be sent to the api/v2 route
The maximum amount of seconds requests should take before returning an answer (defaults to 20)
+The maximum amount of seconds requests should take before returning an answer (defaults to 20)
0 means no maximum, no timeout
-Should always be "Bearer"
-Optional userThe osu! user id of the user who went through the Authorization Code Grant
-Which events should be logged (defaults to none)
-Should always be "Bearer"
+Optional userThe osu! user id of the user who went through the Authorization Code Grant
+Which events should be logged (defaults to none)
+The expiration date of your access_token
+If true, the application will silently use the API.refresh_token right before the API.access_token expires, +as determined by API.expires (defaults to true)
+Valid for an unknown amount of time, allows you to get a new token without going through the Authorization Code Grant again! +Use API.refreshToken to do that
+Get a websocket to get WebSocket events from!
Where the "notification websocket/server" is
-(defaults to the api's server's protocol and a maximum of 1 subdomain being replaced by "wss://notify." (so usually wss://notify.ppy.sh))
Private getSet most of an api's properties, like tokens, token_type, scopes, expiration_date
wss://notify.ppy.sh))
+Private getSet most of an api's properties, like tokens, token_type, scopes, expiration_date
An Object with the client id & secret, grant_type, and stuff that depends of the grant_type
The api which will see its properties change
api, just in case, because in theory it should modify the original object
Private logUse this instead of console.log to log any information
Private logThe function that directly communicates with the API! Almost every functions of the API object uses this function!
The type of request, each endpoint uses a specific one (if it uses multiple, the intent and parameters become different)
What comes in the URL after api/
The things to specify in the request, such as the beatmap_id when looking for a beatmap
Context given by a prior request
A Promise with the API's response
-Static createThe normal way to create an API instance! Make sure to await it
Private updateStatic createThe normal way to create an API instance! Make sure to await it
The ID and the secret of your client, can be found on https://osu.ppy.sh/home/account/edit#new-oauth-application
Optional user: { If the instance is supposed to represent a user, use their Authorization Code and the Application Callback URL of your application!
-The code that appeared as a GET argument when they got redirected to the Application Callback URl (redirect_url)
The code that appeared as a GET argument when they got redirected to the Application Callback URL (redirect_uri)
The Application Callback URL; Where the User has been redirected to after saying "okay" to your application doing stuff
-In seconds
+Optional verbose: "all" | "none" | "errors"Optional server: stringOptional timeout: numberIn seconds
A promise with an API instance
-Readonly getGet extensive beatmap data about whichever beatmap you want!
-Readonly getGet various data about the difficulty of a beatmap!
+Readonly getGet extensive beatmap data about whichever beatmap you want!
+Readonly getGet various data about the difficulty of a beatmap!
You may want to use api.getBeatmapDifficultyAttributesOsu (or Taiko or whatever) instead for better type safety
-Readonly getGet various data about the difficulty of a ctb beatmap!
-Readonly getGet various data about the difficulty of a mania beatmap!
-Readonly getGet various data about the difficulty of an osu! beatmap!
-Readonly getGet various data about the difficulty of a taiko beatmap!
-Readonly getGet data about a Beatmap.Pack using its tag!
+Readonly getGet various data about the difficulty of a ctb beatmap!
+Readonly getGet various data about the difficulty of a mania beatmap!
+Readonly getGet various data about the difficulty of an osu! beatmap!
+Readonly getGet various data about the difficulty of a taiko beatmap!
+Readonly getGet data about a Beatmap.Pack using its tag!
Currently in https://osu.ppy.sh/beatmaps/packs, when hovering a pack, its URL with its tag should be preview by your browser
-Readonly getGet an Array of up to 100 Beatmap.Packs of a specific type!
-Optional cursor_string: stringReadonly getGet the top scores of a beatmap!
+Readonly getGet an Array of up to 100 Beatmap.Packs of a specific type!
+Optional cursor_string: stringReadonly getGet the top scores of a beatmap!
Please check if mods and type seem to be supported or not by the API: https://osu.ppy.sh/docs/index.html#get-beatmap-scores
Readonly getGet the top scores of a beatmap, in the "solo score" format lazer brought with it! +
Readonly getGet the top scores of a beatmap, in the "solo score" format lazer brought with it! More info on GitHub if needed https://github.com/ppy/osu-infrastructure/blob/master/score-submission.md
Please check if mods and type seem to be supported or not by the API: https://osu.ppy.sh/docs/index.html#get-beatmap-scores-non-legacy
Readonly getGet the score on a beatmap made by a specific user (with specific mods and on a specific ruleset if needed)
+Readonly getGet the score on a beatmap made by a specific user (with specific mods and on a specific ruleset if needed)
An Object with the position of the score according to the specified Mods and Ruleset, and with the score itself
-Readonly getGet the scores on a beatmap made by a specific user (with the possibility to specify if the scores are on a convert)
-Readonly getGet extensive beatmap data for up to 50 beatmaps at once!
-Readonly lookupGet extensive beatmap data about whichever beatmap you want!
-Optional checksum?: stringOptional filename?: stringOptional id?: numberReadonly getGet extensive beatmapset data about whichever beatmapset you want!
-Readonly getGet complex data about the posts of a beatmapset's discussion or of a user!
+Readonly getGet the scores on a beatmap made by a specific user (with the possibility to specify if the scores are on a convert)
+Readonly getGet extensive beatmap data for up to 50 beatmaps at once!
+Readonly lookupGet extensive beatmap data about whichever beatmap you want!
+Optional checksum?: stringOptional filename?: stringOptional id?: numberReadonly getGet extensive beatmapset data about whichever beatmapset you want!
+Readonly getGet complex data about the posts of a beatmapset's discussion or of a user!
Optional from: { Optional discussion?: number | DiscussionOptional user?: number | UserOptional types: ("first" | "reply" | "system")[]Optional config: Beatmapset.Config(2024-03-11) For months now, the API's documentation says the response is likely to change, so beware
Relevant posts and info about them
-Readonly getGet complex data about the votes of a beatmapset's discussions or/and received/given by a specific user!
+Readonly getGet complex data about the votes of a beatmapset's discussions or/and received/given by a specific user!
Optional from: { Optional discussion?: number | DiscussionOptional vote_Optional vote_Optional score: 1 | -1Optional config: Beatmapset.Config(2024-03-11) For months now, the API's documentation says the response is likely to change, so beware
Relevant votes and info about them
-Readonly getGet complex data about the discussion page of any beatmapet that you want!
+Readonly getGet complex data about the discussion page of any beatmapet that you want!
Optional from: { Optional beatmapset?: number | BeatmapsetOptional status?: "all" | "ranked" | "qualified" | "disqualified" | "never_qualified"Optional user?: number | UserOptional filter: { Optional only_Optional types?: ("suggestion" | "problem" | "mapper_note" | "praise" | "hype" | "review")[]Optional config: Beatmapset.Config(2024-03-11) For months now, the API's documentation says the response is likely to change, so beware
Relevant discussions and info about them
-Readonly getGet complex data about the events of a beatmapset and the users involved with them!
+Readonly getGet complex data about the events of a beatmapset and the users involved with them!
Optional from: { Optional beatmapset?: number | BeatmapsetOptional max_Optional min_Optional user?: number | UserOptional types: ("nominate" | "love" | "remove_from_loved" | "qualify" | "disqualify" | "approve" | "rank" | "kudosu_allow" | "kudosu_deny" | "kudosu_gain" | "kudosu_lost" | "kudosu_recalculate" | "issue_resolve" | "issue_reopen" | "discussion_lock" | "discussion_unlock" | "discussion_delete" | "discussion_restore" | "discussion_post_delete" | "discussion_post_restore" | "nomination_reset" | "nomination_reset_received" | "genre_edit" | "language_edit" | "nsfw_toggle" | "offset_edit" | "tags_edit" | "beatmap_owner_change")[]Optional config: Beatmapset.Config(2024-03-11) For months now, the API's documentation says the response is likely to change, so beware, and also there's no documentation for this route in the API, so this is only the result of my interpretation of the website's code lol
Relevant events and users
-Readonly lookupGet extensive data about a beatmapset by using a beatmap!
-Readonly searchSearch for beatmapsets as if you were on the website or on lazer!
-Optional query: { Optional categories?: "Any" | "Ranked" | "Qualified" | "Loved" | "Favourites" | "Pending" | "WIP" | "Graveyard" | "My Maps"Filter in sets depending on their status or on their relation with the authorized user (defaults to all that have a leaderboard)
+Readonly lookupGet extensive data about a beatmapset by using a beatmap!
+Readonly searchSearch for beatmapsets as if you were on the website or on lazer!
+Optional query: { Optional categories?: "Any" | "Ranked" | "Qualified" | "Loved" | "Favourites" | "Pending" | "WIP" | "Graveyard" | "My Maps"Filter in sets depending on their status or on their relation with the authorized user (defaults to all that have a leaderboard)
Optional cursor_The thing you've got from a previous request to get another page of results!
Optional extra?: ("must_have_video" | "must_have_storyboard")[]Should all sets have a video, a storyboard, maybe both at once?
Optional general?: ("Recommended difficulty" | "Include converted beatmaps" | "Subscribed mappers" | "Spotlighted beatmaps" | "Featured Artists")[]Various filters to activate
@@ -196,36 +201,36 @@Relevant events and users
Optional sort?: { Sort by what, in ascending/descending order
This does not bypass the current osu!supporter requirement for certain filters
Relevant Beatmapsets that contain Beatmaps, and a cursor_string to allow you to look for more of the same!
-Readonly getGet details about the version/update/build of something related to osu!
-Readonly getGet up to 21 versions/updates/builds!
+Readonly getGet details about the version/update/build of something related to osu!
+Readonly getGet up to 21 versions/updates/builds!
Optional stream: stringOptional range: { Optional from?: stringThe name of the build
Optional to?: string | numberThe name or the id of the build
-Readonly getAn effective way to get all available streams, as well as their latest version!
-Readonly lookupGet details about the version/update/build of something related to osu!
-Readonly createCreate a new announcement!
+Readonly getAn effective way to get all available streams, as well as their latest version!
+Readonly lookupGet details about the version/update/build of something related to osu!
+Readonly createCreate a new announcement!
From my understanding, this WILL 403 unless the user is kinda special
The newly created channel!
-Readonly createCreate/Open/Join a private messages chat channel!
+Readonly createCreate/Open/Join a private messages chat channel!
The newly created channel!
-Readonly getGet a ChatChannel that you have joined, and the users in it if it is a private channel!
+Readonly getGet a ChatChannel that you have joined, and the users in it if it is a private channel!
Will 404 if the user has not joined the channel (use joinChatChannel for that)
Readonly getGet a list of all publicly joinable channels!
-Readonly getGet the recent messages of a specific ChatChannel!
-Readonly joinJoin a public or multiplayer ChatChannel, allowing you to interact with it!
-Readonly keepNeeds to be done periodically to reset chat activity timeout
+Readonly getGet a list of all publicly joinable channels!
+Readonly getGet the recent messages of a specific ChatChannel!
+Readonly joinJoin a public or multiplayer ChatChannel, allowing you to interact with it!
+Readonly keepNeeds to be done periodically to reset chat activity timeout
Optional since: { Optional message?: number | MessageOptional user_Every 30 seconds is a good idea
A list of recent silences
-Readonly leaveLeave/Close a public ChatChannel!
-Readonly markMark a certain channel as read up to a given message!
-Readonly sendSend a message in a ChatChannel!
-The newly sent ChatMessage!
-Readonly sendSend a private message to someone!
-You don't need to use createChatPrivateChannel before sending a message
Readonly leaveLeave/Close a public ChatChannel!
+Readonly markMark a certain channel as read up to a given message!
+Readonly sendSend a message in a ChatChannel!
+The newly sent ChatMessage!
+Readonly sendSend a private message to someone!
+You don't need to use createChatPrivateChannel before sending a message
The message you sent
-Readonly getGet a specific comment by using its id!
-Readonly getGet comments that meet any of your requirements!
-Optional from: { Optional parent: number | CommentOptional sort: { Optional after?: number | CommentOptional cursor?: null | { Optional type?: "new" | "top" | "old"Readonly getGet everything note-worthy that happened on osu! recently!
-Readonly createCreate a new ForumTopic in the forum of your choice!
+Readonly getGet a specific comment by using its id!
+Readonly getGet comments that meet any of your requirements!
+Optional from: { Optional parent: number | CommentOptional sort: { Optional after?: number | CommentOptional cursor?: null | { Optional type?: "new" | "top" | "old"Readonly getGet everything note-worthy that happened on osu! recently!
+Readonly createCreate a new ForumTopic in the forum of your choice!
Optional poll: { Optional hide_Should the results of the poll be hidden while the voting period is still active? (defaults to false)
Length of voting period in days, 0 means forever
Optional max_The maximum amount of votes per user! (defaults to 1)
@@ -233,59 +238,59 @@The message you sent
Optional vote_Do you allow users to change their vote? (defaults to false)
Some users may not be allowed to do that, such as newly registered users, so this can 403 even with the right scopes
An object with the topic you've made, and its first initial post (which uses your text)
Readonly editEdit a ForumPost! Note that it can be the initial one of a ForumTopic!
+Readonly editEdit a ForumPost! Note that it can be the initial one of a ForumTopic!
The edited ForumPost
-Readonly editEdit the title of a Forum.Topic!
+Readonly editEdit the title of a Forum.Topic!
Use editForumPost if you wanna edit the post at the top of the topic
The edited ForumTopic
-Readonly getGet a forum topic, as well as its main post (content) and the posts that were sent in it!
+Readonly getGet a forum topic, as well as its main post (content) and the posts that were sent in it!
Optional config: { Optional cursor_Use a response's cursor_string with the same parameters to get the next "page" of results, so posts in this instance!
Optional first_The id (or the post itself) of the first post to be returned in posts (irrelevant if using a cursor_string)
Optional limit?: numberHow many posts maximum, up to 50
Optional sort?: "id_desc" | "id_asc""id_asc" to have the oldest post at the beginning of the posts array, "id_desc" to have the newest instead
The oldest post of a topic is the text of a topic
-Readonly replyMake and send a Forum.Post in a Forum.Topic!
+Readonly replyMake and send a Forum.Post in a Forum.Topic!
Replying when the last post was made by the authorized user will likely cause the server to return a 403
The reply you've made, as a Forum.Post!
-Readonly searchLook for a user like you would on the website!
-Readonly searchLook for a wiki page like you would on the website!
-Readonly getGet data about a lazer multiplayer room (realtime or playlists)!
-Readonly getGet data about a lazer multiplayer room (realtime or playlists)!
+Readonly searchLook for a user like you would on the website!
+Readonly searchLook for a wiki page like you would on the website!
+Readonly getGet data about a lazer multiplayer room (realtime or playlists)!
+Readonly getGet data about a lazer multiplayer room (realtime or playlists)!
Optional query: { Optional first_Which match should be featured at index 0 of the returned array? Will get one with a similar id if it is unavailable
You can use this argument differently to get all matches before/after (depending of query.sort) a certain match,
by adding +1/-1 to its id! So if you want all matches after match_id 10 with sorting is_desc, just have this argument be 10 + 1, or 11!
Optional limit?: numberThe maximum amount of elements returned in the array (defaults to 50)
Optional sort?: "id_desc" | "id_asc""id_desc" has the biggest id (most recent start_time) at the beginning of the array, "id_asc" is the opposite (defaults to id_desc)
-Readonly getGet data about a lazer multiplayer room (realtime or playlists)!
-Optional cursor_string: stringReadonly getGet data about a lazer multiplayer room (realtime or playlists)!
-Readonly getGet data about a lazer multiplayer room (realtime or playlists)!
-Readonly getGet data about a lazer multiplayer room (realtime or playlists)!
-Readonly getGet a NewsPost, its content, and the NewsPosts right before and right after it!
-Readonly getGet all the NewsPosts of a specific year!
+Readonly getGet data about a lazer multiplayer room (realtime or playlists)!
+Optional cursor_string: stringReadonly getGet data about a lazer multiplayer room (realtime or playlists)!
+Readonly getGet data about a lazer multiplayer room (realtime or playlists)!
+Readonly getGet data about a lazer multiplayer room (realtime or playlists)!
+Readonly getGet a NewsPost, its content, and the NewsPosts right before and right after it!
+Readonly getGet all the NewsPosts of a specific year!
If the specified year is invalid/has no news, it fallbacks to the default year
-Readonly getGet the replay for a score!
+Readonly getGet the replay for a score!
The correctly encoded content of what would be a replay file (you can just fs.writeFileSync with it!)
-Readonly getGet ALL legacy spotlights! (2009-2020, somewhat known as charts/ranking charts, available @ https://osu.ppy.sh/rankings/osu/charts)
+Readonly getGet ALL legacy spotlights! (2009-2020, somewhat known as charts/ranking charts, available @ https://osu.ppy.sh/rankings/osu/charts)
The data for newer spotlights (2020-, somewhat known as seasons) can be obtained through getRoom()
but you can't really get the id of those newer spotlights without going through the website's URLs (https://osu.ppy.sh/seasons/latest) as far as I know :(
Get the backgrounds made and selected for this season or for last season!
+Get the backgrounds made and selected for this season or for last season!
When the season ended, and for each background, its URL and its artist
-Readonly getGet the top countries of a specific ruleset!
-Readonly getGet the top 50 players who have the most total kudosu!
-Readonly getGet the rankings of a spotlight from 2009 to 2020 on a specific ruleset!
-Readonly getGet the top players of the game, with some filters!
+Readonly getGet the top countries of a specific ruleset!
+Readonly getGet the top 50 players who have the most total kudosu!
+Readonly getGet the rankings of a spotlight from 2009 to 2020 on a specific ruleset!
+Readonly getGet the top players of the game, with some filters!
Optional config: { Optional country?: stringOnly get players from a specific country, using its ISO 3166-1 alpha-2 country code! (France would be FR, United States US)
Optional filter?: "all" | "friends"What kind of players do you want to see? Keep in mind friends has no effect if no authorized user
Optional page?: numberImagine the array you get as a page, it can only have a maximum of 50 players, while 50 others may be on the next one
Optional variant?: "4k" | "7k"If type is performance and ruleset is mania, choose between 4k and 7k!
Readonly getGet user data of each friend of the authorized user
-Readonly getGet extensive user data about the authorized user
-Readonly getGet extensive user data about whoever you want!
-Readonly getGet beatmaps favourited or made by a user!
-Readonly getGet data about the activity of a user kudosu-wise!
-Readonly getGet the beatmaps most played by a user!
-Readonly getGet an array of Events of different types that relate to a user's activity during the last 31 days! (or 100 activities, whatever comes first)
Readonly getGet "notable" scores from a user
-Readonly getGet user data for up to 50 users at once!
-Readonly getGet a wiki page!
-Generated using TypeDoc
Readonly getGet user data of each friend of the authorized user
+Readonly getGet extensive user data about the authorized user
+Readonly getGet extensive user data about whoever you want!
+Readonly getGet beatmaps favourited or made by a user!
+Readonly getGet data about the activity of a user kudosu-wise!
+Readonly getGet the beatmaps most played by a user!
+Readonly getGet an array of Events of different types that relate to a user's activity during the last 31 days! (or 100 activities, whatever comes first)
Readonly getGet "notable" scores from a user
+Readonly getGet user data for up to 50 users at once!
+Readonly getGet a wiki page!
+Generated using TypeDoc
If the API throws an error, it should always be an APIError!
The type of resource that was requested from the server
-The reason why things didn't go as expected
-Optional original_The error that caused the api to throw an APIError in the first place, if there is one
The filters that were used to specify what resource was wanted
-The server to which the request was sent
-Optional status_The status code that was returned by the server, if there is one
-Generated using TypeDoc
The type of resource that was requested from the server
+The reason why things didn't go as expected
+Optional original_The error that caused the api to throw an APIError in the first place, if there is one
+The filters that were used to specify what resource was wanted
+The server to which the request was sent
+Optional status_The status code that was returned by the server, if there is one
+Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Generated using TypeDoc
Optional mods: number | string[] | Mod[]Can be a bitset of mods, an array of mod acronyms, or an array of Mods (ignores mod settings) (defaults to No Mod)
Optional ruleset: RulesetUseful to specify if the beatmap is a convert (defaults to the ruleset the beatmap was intended for)
You may want to use api.getBeatmapDifficultyAttributesOsu (or Taiko or whatever) instead for better type safety
-Generated using TypeDoc
You can create an API instance without directly providing an access_token by using the API's
-createAsyncfunction! API.createAsync