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!
The key that allows you to talk with the API
The ID of your client, which you can get on https://osu.ppy.sh/home/account/edit#oauth
The Secret of your client, which you can get or reset on https://osu.ppy.sh/home/account/edit#oauth
The expiration date of your access_token
Valid for an unknown amount of time, it allows you to get a new token without going through the Authorization Code Grant again! Use API.refreshToken to do that
If true, upon failing a request due to a 401, it will use the API.refresh_token if it exists (defaults to true)
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)
In seconds, how long should it wait until retrying? (defaults to 2)
How many retries maximum before throwing an APIError (defaults to 4)
Should it retry a request upon successfully refreshing the token due to API.refresh_token_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)
Used by practically every method to interact with the API.server (defaults to api/v2)
Used for getting an API.access_token and using your API.refresh_token (defaults to oauth/token)
The base url of the server where the requests should land (defaults to https://osu.ppy.sh)
The maximum amount of seconds requests should take before returning an answer (defaults to 20)
Should always be "Bearer"
The osu! user id of the user who went through the Authorization Code Grant
Which events should be logged (defaults to none)
The 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
Optional
settings: Omit<RequestInit, "body">Additional settings to add to the current settings of the fetch()
request
Context given by a prior request
A Promise with the API's response
Revoke your current token! This revokes the refresh token as well
Uses API.route_api instead of API.route_token, as normally expected by the server
You can use this to specify additional settings for the method you're going to call, such as headers
, an AbortSignal
, and more advanced things!
You may get more info at https://developer.mozilla.org/en-US/docs/Web/API/RequestInit#instance_properties
A special version of the API
that changes how requests are done
Static
createThe normal way to create an API instance! Make sure to await
it
The ID of your client, which you can get on https://osu.ppy.sh/home/account/edit#oauth
The Secret of your client, which you can get or reset on https://osu.ppy.sh/home/account/edit#oauth
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_uri
)
The Application Callback URL; Where the User has been redirected to after saying "okay" to your application doing stuff
Optional
settings: Partial<API>Additional settings you'd like to specify now rather than later, check out the Accessors at https://osu-v2.taevas.xyz/classes/API.html
A promise with an API instance
Readonly
getGet extensive beatmap data about whichever beatmap you want!
Get extensive beatmap data about whichever beatmap you want!
Readonly
getGet various data about the difficulty of a beatmap!
Get various data about the difficulty of a beatmap!
The Beatmap in question
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)
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!
Get 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
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!
Get an Array of up to 100 Beatmap.Packs of a specific type!
The type of the BeatmapPacks (defaults to standard)
Optional
cursor_string: stringUse a response's cursor_string
with the same parameters to get the next "page" of results!
Readonly
getGet extensive beatmap data for up to 50 beatmaps at once!
Get extensive beatmap data for up to 50 beatmaps at once!
Readonly
getGet the top scores of a beatmap!
Get 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
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
getYou may want to use getScores
instead, nowadays it seems to do just about the same thing
Get 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
You may want to use getScores
instead, nowadays it seems to do just about the same thing
Get 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
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)
Get 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
lookupGet extensive beatmap data about whichever beatmap you want!
Get extensive beatmap data about whichever beatmap you want!
What to specify in order to find the right beatmap
Optional
checksum?: stringOptional
filename?: stringOptional
id?: numberReadonly
getGet extensive beatmapset data about whichever beatmapset you want!
Get extensive beatmapset data about whichever beatmapset you want!
The beatmapset or the id of the beatmapset you're trying to get
Readonly
getGet complex data about the posts of a beatmapset's discussion or of a user!
Get complex data about the posts of a beatmapset's discussion or of a user!
Optional
from: { From where/who are the posts coming from? A specific discussion, a specific user?
Optional
discussion?: number | DiscussionOptional
user?: number | UserOptional
types: ("first" | "reply" | "system")[]What kind of posts?
Optional
config: Beatmapset.ConfigHow many results maximum, how to sort them, which page of those, maybe a cursor_string...
Relevant posts and info about them
Readonly
getGet complex data about the discussion page of any beatmapet that you want!
Get complex data about the discussion page of any beatmapet that you want!
Optional
from: { From where/who are the discussions coming from? Maybe only qualified sets?
Optional
beatmapset?: number | BeatmapsetOptional
status?: Optional
user?: number | UserOptional
filter: { Should those discussions only be unresolved problems, for example?
Optional
only_Optional
types?: (Optional
config: Beatmapset.ConfigHow many results maximum, how to sort them, which page of those, maybe a cursor_string...
Relevant discussions and info about them
Readonly
getGet complex data about the votes of a beatmapset's discussions or/and received/given by a specific user!
Get complex data about the votes of a beatmapset's discussions or/and received/given by a specific user!
Optional
from: { The discussion with the votes, the user who voted, the user who's gotten the votes...
Optional
discussion?: number | DiscussionOptional
vote_Optional
vote_Optional
score: 1 | -1An upvote (1) or a downvote (-1)
Optional
config: Beatmapset.ConfigHow many results maximum, how to sort them, which page of those, maybe a cursor_string...
Relevant votes and info about them
Readonly
getGet complex data about the events of a beatmapset and the users involved with them!
Get complex data about the events of a beatmapset and the users involved with them!
Optional
from: { Which beatmapset, or caused by which user? When?
Optional
beatmapset?: number | BeatmapsetOptional
max_Optional
min_Optional
user?: number | UserOptional
types: (What kinds of events?
Optional
config: Beatmapset.ConfigHow many results maximum, how to sort them, which page of those, maybe a cursor_string...
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!
Search for beatmapsets as if you were on the website or on lazer!
Optional
query: { All the filters and sorting options that you'd normally find on the website or on lazer
Optional
categories?: 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?: (Various filters to activate
Optional
genre?: Specify the musical genre of the music of the beatmapsets you're searching for (don't specify to get any genre)
Optional
hide_Use this to hide all sets that are marked as explicit
Optional
keywords?: stringWhat you'd put in the searchbar, like the name of a beatmapset or a mapper!
Optional
language?: Specify the spoken language of the music of the beatmapsets you're searching for (don't specify to get any language)
Optional
mode?: RulesetOnly get sets that have maps that you can play in the ruleset of your choice
Optional
played?: "Played" | "Unplayed"Does the authorized user with osu!supporter have already played those sets, or have they not played them yet?
Optional
rank_Does the authorized user with osu!supporter have already achieved certain ranks on those sets?
Optional
sort?: { Sort by what, in ascending/descending order
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!
Get details about the version/update/build of something related to osu!
The name of the thing related to osu!, like lazer
, web
, cuttingedge
, beta40
, stable40
The name of the version! Usually something like 2023.1026.0
for lazer, or 20230326
for stable
Readonly
getGet up to 21 versions/updates/builds!
Get up to 21 versions/updates/builds!
Optional
stream: stringOnly get builds from a specific stream
Optional
range: { Get builds that were released before/after (and including) those builds
Optional
from?: stringThe name of the build
Optional
to?: string | numberThe name or the id of the build
changelog_entries
will have a message
property if markdown
, message_html
property if html
(defaults to both)
Readonly
getAn effective way to get all available streams, as well as their latest version!
An 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!
Get details about the version/update/build of something related to osu!
A stream name like lazer
, a build version like 2023.1026.0
, or the id of a build
changelog_entries
will have a message
property if markdown
, message_html
property if html
(defaults to both)
Readonly
createCreate a new announcement!
Readonly
createCreate/Open/Join a private messages chat channel!
Readonly
getGet a ChatChannel that you have joined, and the users in it if it is a private channel!
Get a ChatChannel that you have joined, and the users in it if it is a private channel!
Readonly
getGet a list of all publicly joinable channels!
Readonly
getGet the recent messages of a specific ChatChannel!
Get the recent messages of a specific ChatChannel!
The Channel you wanna get the messages from
The maximum amount of messages you want to get, up to 50! (defaults to 20)
Optional
since: number | MessageGet the messages sent after this message
Optional
until: number | MessageGet the messages sent up to but not including this message
Readonly
joinJoin a public or multiplayer ChatChannel, allowing you to interact with it!
Join a public or multiplayer ChatChannel, allowing you to interact with it!
Readonly
keepNeeds to be done periodically to reset chat activity timeout
Needs to be done periodically to reset chat activity timeout
Optional
since: { UserSilences that are before that will not be returned!
Optional
message?: number | MessageOptional
user_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!
Readonly
sendSend a private message to someone!
Readonly
getGet a specific comment by using its id!
Readonly
getGet comments that meet any of your requirements!
Get comments that meet any of your requirements!
Optional
from: { From where are the comments coming from? Maybe a beatmapset, but then, which beatmapset?
Optional
parent: number | CommentThe comments are replying to which comment? Make the id 0 to filter out replies (and only get top level comments)
Optional
sort: { Should the comments be sorted by votes? Should they be from after a certain date? Maybe you can give a cursor?
Optional
after?: number | CommentOptional
cursor?: null | { Optional
type?: "new" | "old" | "top"Readonly
getGet everything note-worthy that happened on osu! recently!
Get everything note-worthy that happened on osu! recently!
"id_asc" to have the oldest recent event first, "id_desc" to have the newest instead (defaults to id_desc)
Optional
cursor_string: stringUse a response's cursor_string
with the same parameters to get the next "page" of results, so events
in this instance!
Readonly
createCreate a new ForumTopic in the forum of your choice!
Create a new ForumTopic in the forum of your choice!
The id of the forum you're creating your topic in
The topic's title
The first post's content/message
Optional
poll: { If you want to make a poll, specify the parameters of that 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)
The things the users can vote for
Optional
vote_Do you allow users to change their vote? (defaults to false)
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 the title of a Forum.Topic!
Readonly
getGet a forum topic, as well as its main post (content) and the posts that were sent in it!
Get a forum topic, as well as its main post (content) and the posts that were sent in it!
An object with the id of the topic in question
Optional
config: { How many results maximum, how to sort them, etc...
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
Readonly
replyMake and send a Forum.Post in a Forum.Topic!
Readonly
searchLook for a user like you would on the website!
Look for a user like you would on the website!
What you would put in the searchbar
You normally get the first 20 results, but if page is 2, you'd get results 21 to 40 instead for example! (defaults to 1)
Readonly
searchLook for a wiki page like you would on the website!
Look for a wiki page like you would on the website!
What you would put in the searchbar
You normally get the first 50 results, but if page is 2, you'd get results 51 to 100 instead for example! (defaults to 1)
Readonly
getGet data of a multiplayer lobby from the stable (non-lazer) client that have URLs with community/matches
or mp
Get data of a multiplayer lobby from the stable (non-lazer) client that have URLs with community/matches
or mp
The id of a match can be found at the end of its URL
Optional
query: { Filter and limit the amount of events shown
Optional
after?: number | Multiplayer.Match.EventFilter FOR events AFTER this one
Optional
before?: number | Multiplayer.Match.EventFilter FOR events BEFORE this one
Optional
limit?: numberFrom 1 to 101 events (defaults to 100)
Readonly
getGet the info about several matches!
Get the info about several matches!
Optional
query: { The id of the first match of the array, and the sorting and size of said array
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
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 the scores on a specific item of a room!
Get the scores on a specific item of a room!
An object with the id of the item in question, as well as the id of the room
How many scores maximum? Defaults to 50, the maximum the API will return
Sort by scores, ascending or descending? Defaults to descending
Optional
cursor_string: stringUse a Multiplayer.Scores' params
and cursor_string
to get the next page (scores 51 to 100 for example)
(2024-03-04) This may not work for rooms from before March 5th 2024, use at your own risk https://github.com/ppy/osu-web/issues/10725
(2024-03-04) This may not work for rooms from before March 5th 2024, use at your own risk https://github.com/ppy/osu-web/issues/10725
Readonly
getGet data about a lazer multiplayer room (realtime or playlists)!
Readonly
getGet the room stats of all the users of that room!
Get the room stats of all the users of that room!
An object with the leaderboard, and the score and position of the authorized user under user_score
Readonly
getGet playlists/realtime rooms that are active, that have ended, that the user participated in, that the user made, or just simply any room!
Get playlists/realtime rooms that are active, that have ended, that the user participated in, that the user made, or just simply any room!
Whether the multiplayer rooms are in playlist format (like current spotlights) or realtime
The state of the room, or the relation of the authorized user with the room
The maximum amount of rooms to return, defaults to 10
Sort (where most recent is first) by creation date or end date, defaults to the creation date
Optional
season_id: numberOnly get rooms (playlists) that belong to a specific (modern) Beatmap Spotlights season id
(so 5
'd be summer 2020's mania rooms, not winter 2022!!)
Readonly
getGet a NewsPost, its content, and the NewsPosts right before and right after it!
Get a NewsPost, its content, and the NewsPosts right before and right after it!
Readonly
getGet all the NewsPosts of a specific year!
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!
Get 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!
Get the rankings of a spotlight from 2009 to 2020 on a specific ruleset!
Each spotlight has a different ranking (and often maps) depending on the ruleset
The spotlight in question
What kind of players do you want to see? Keep in mind friends
has no effect if no authorized user (defaults to all)
Readonly
getGet the top players of the game, with some filters!
Get the top players of the game, with some filters!
Self-explanatory, is also known as "Gamemode"
Rank players by their performance points or by their ranked score?
Optional
config: { Specify which page, country, filter out non-friends...
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?: "friends" | "all"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 the replay for a score!
Readonly
getGet ALL legacy spotlights! (2009-2020, somewhat known as charts/ranking charts, available @ https://osu.ppy.sh/rankings/osu/charts)
Get 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 :(
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 :(
Readonly
getGet user data of each friend of the authorized user
Readonly
getGet extensive user data about the authorized user
Get 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!
Get beatmaps favourited or made by a user!
Readonly
getGet data about the activity of a user kudosu-wise!
Get 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 type
s that relate to a user's activity during the last 31 days! (or 100 activities, whatever comes first)
Get an array of Events of different type
s that relate to a user's activity during the last 31 days! (or 100 activities, whatever comes first)
Readonly
getGet user data for up to 50 users at once!
Get user data for up to 50 users at once!
Readonly
getGet "notable" scores from a user
Get "notable" scores from a user
The user who set the scores
Do you want scores: in the user's top 100, that are top 1 on a beatmap, that have been recently set?
Optional
ruleset: RulesetThe Ruleset the scores were made in (defaults to user's default Ruleset)
Do you also want lazer scores and failed scores? (defaults to true for lazer & false for fails)
Optional
fails?: booleanOptional
lazer?: booleanOptional
config: User.ConfigArray limit & offset
Readonly
lookupLookup user data for up to 50 users at once!
Lookup user data for up to 50 users at once!
Readonly
generateGet a websocket to get WebSocket events from!
Get a websocket to get WebSocket events from!
The "notification websocket/server" URL (defaults to wss://notify.ppy.sh)
Readonly
getGet a wiki page!
Get a wiki page!
What's in the page's URL after https://osu.ppy.sh/wiki/
(so the title, after the subtitle if there is a subtitle)
(An example for https://osu.ppy.sh/wiki/en/Game_mode/osu!
would be Game_mode/osu!
)
Lowercase language tag ("fr" for french, "pt-br" for brazilian portuguese) (defaults to en)
You can create an API instance without directly providing an access_token by using API.createAsync!