Class API

You can create an API instance without directly providing an access_token by using API.createAsync!

Hierarchy (View Summary)

API
- ChildAPI

Index

Constructors

constructor

new API(properties: Partial<API>): API
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!
Parameters
- properties: Partial<API>
Returns API
- Defined in index.ts:87

Accessors

access_token

get access_token(): string
The key that allows you to talk with the API

Returns string
- Defined in index.ts:223
set access_token(token: string): void
Parameters
- token: string
Returns void
- Defined in index.ts:224

client_id

get client_id(): number
The ID of your client, which you can get on https://osu.ppy.sh/home/account/edit#oauth

Returns number
- Defined in index.ts:130
set client_id(client_id: number): void
Parameters
- client_id: number
Returns void
- Defined in index.ts:131

client_secret

get client_secret(): string
The Secret of your client, which you can get or reset on https://osu.ppy.sh/home/account/edit#oauth

Returns string
- Defined in index.ts:135
set client_secret(client_secret: string): void
Parameters
- client_secret: string
Returns void
- Defined in index.ts:136

expires

get expires(): Date
The expiration date of your access_token

Returns Date
- Defined in index.ts:233
set expires(date: Date): void
Parameters
- date: Date
Returns void
- Defined in index.ts:234

headers

get headers(): { [key: string]: any }
Used in practically all requests, those are all the headers the package uses excluding Authorization, the one with the token

Returns { [key: string]: any }
- Defined in index.ts:166
set headers(headers: { [key: string]: any }): void
Parameters
- headers: { [key: string]: any }
Returns void
- Defined in index.ts:167

refresh_token

get refresh_token(): undefined | string
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

Returns undefined | string
- Defined in index.ts:306
set refresh_token(token: undefined | string): void
Parameters
- token: undefined | string
Returns void
- Defined in index.ts:307

refresh_token_on_401

get refresh_token_on_401(): boolean
If true, upon failing a request due to a 401, it will use the API.refresh_token if it exists (defaults to true)

Returns boolean
- Defined in index.ts:314
set refresh_token_on_401(refresh: boolean): void
Parameters
- refresh: boolean
Returns void
- Defined in index.ts:315

refresh_token_on_expires

get refresh_token_on_expires(): boolean
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)

Returns boolean
- Defined in index.ts:322
set refresh_token_on_expires(enabled: boolean): void
Parameters
- enabled: boolean
Returns void
- Defined in index.ts:323

refresh_token_timer

get refresh_token_timer(): undefined | Timeout
Returns undefined | Timeout
- Defined in index.ts:329
set refresh_token_timer(timer: Timeout): void
Parameters
- timer: Timeout
Returns void
- Defined in index.ts:330

retry_delay

get retry_delay(): number
In seconds, how long should it wait after a request failed before retrying? (defaults to 2)

Returns number
- Defined in index.ts:192
set retry_delay(retry_delay: number): void
Parameters
- retry_delay: number
Returns void
- Defined in index.ts:193

retry_maximum_amount

get retry_maximum_amount(): number
How many retries maximum before throwing an APIError (defaults to 4)

Returns number
Remarks
Pro tip: Set that to 0 to completely disable retries!
- Defined in index.ts:200
set retry_maximum_amount(retry_maximum_amount: number): void
Parameters
- retry_maximum_amount: number
Returns void
- Defined in index.ts:201

retry_on_automatic_token_refresh

get retry_on_automatic_token_refresh(): boolean
Should it retry a request upon successfully refreshing the token due to API.refresh_token_on_401 being true? (defaults to true)

Returns boolean
- Defined in index.ts:205
set retry_on_automatic_token_refresh(
retry_on_automatic_token_refresh: boolean,
): void
Parameters
- retry_on_automatic_token_refresh: boolean
Returns void
- Defined in index.ts:206

retry_on_status_codes

get retry_on_status_codes(): number[]
Upon failing a request and receiving a response, because of which received status code should the request be retried? (defaults to [429])

Returns number[]
- Defined in index.ts:210
set retry_on_status_codes(retry_on_status_codes: number[]): void
Parameters
- retry_on_status_codes: number[]
Returns void
- Defined in index.ts:211

retry_on_timeout

get retry_on_timeout(): boolean
Should it retry a request if that request failed because it has been aborted by the API.timeout? (defaults to false)

Returns boolean
- Defined in index.ts:215
set retry_on_timeout(retry_on_timeout: boolean): void
Parameters
- retry_on_timeout: boolean
Returns void
- Defined in index.ts:216

route_api

get route_api(): (string | number)[]
Used by practically every method to interact with the API.server (defaults to api/v2)

Returns (string | number)[]
- Defined in index.ts:145
set route_api(route_api: (string | number)[]): void
Parameters
- route_api: (string | number)[]
Returns void
- Defined in index.ts:146

route_token

get route_token(): (string | number)[]
Used for getting an API.access_token and using your API.refresh_token (defaults to oauth/token)

Returns (string | number)[]
- Defined in index.ts:150
set route_token(route_token: (string | number)[]): void
Parameters
- route_token: (string | number)[]
Returns void
- Defined in index.ts:151

scopes

get scopes(): Scope[]
The Scopes your application has, assuming it acts as a user

Returns Scope[]
- Defined in index.ts:155
set scopes(scopes: Scope[]): void
Parameters
- scopes: Scope[]
Returns void
- Defined in index.ts:156

server

get server(): string
The base url of the server where the requests should land (defaults to https://osu.ppy.sh)

Returns string
- Defined in index.ts:140
set server(server: string): void
Parameters
- server: string
Returns void
- Defined in index.ts:141

timeout

get timeout(): number
The maximum amount of seconds requests should take before returning an answer (defaults to 20)

Returns number
Remarks
0 means no maximum, no timeout
- Defined in index.ts:187
set timeout(timeout: number): void
Parameters
- timeout: number
Returns void
- Defined in index.ts:188

token_type

get token_type(): string
Should always be "Bearer"

Returns string
- Defined in index.ts:228
set token_type(token: string): void
Parameters
- token: string
Returns void
- Defined in index.ts:229

user

get user(): undefined | number
The osu! user id of the user who went through the Authorization Code Grant

Returns undefined | number
- Defined in index.ts:171
set user(user: undefined | number): void
Parameters
- user: undefined | number
Returns void
- Defined in index.ts:172

verbose

get verbose(): undefined | "none" | "all" | "errors"
Which events should be logged (defaults to none)

Returns undefined | "none" | "all" | "errors"
- Defined in index.ts:179
set verbose(verbose: undefined | "none" | "all" | "errors"): void
Parameters
- verbose: undefined | "none" | "all" | "errors"
Returns void
- Defined in index.ts:180

Methods

refreshToken

refreshToken(): Promise<boolean>
Returns Promise<boolean>
Whether or not the token has been refreshed
- Defined in index.ts:365

request

request(
    method: "get" | "post" | "put" | "delete",
    endpoint: (string | number)[],
    parameters?: { [k: string]: any },
    settings?: Omit<RequestInit, "body">,
    info?: { just_refreshed: boolean; number_try: number },
): Promise<any>
The function that directly communicates with the API! Almost every functions of the API object uses this function!
Parameters
- method: "get" | "post" | "put" | "delete"
  The type of request, each endpoint uses a specific one (if it uses multiple, the intent and parameters become different)
- endpoint: (string | number)[]
  What comes in the URL after api/, **DO NOT USE TEMPLATE LITERALS () OR THE ADDITION OPERATOR (+), put everything separately for type safety** @param parameters The things to specify in the request, such as the beatmap_id when looking for a beatmap @param settings Additional settings **to add** to the current settings of the fetch()` request
- parameters: { [k: string]: any } = {}
- Optionalsettings: Omit<RequestInit, "body">
- info: { just_refreshed: boolean; number_try: number } = ...
  Context given by a prior request
Returns Promise<any>
A Promise with the API's response
- Defined in index.ts:421

revokeToken

revokeToken(): Promise<void>
Revoke your current token! This revokes the refresh token as well

Returns Promise<void>
Remarks
Uses API.route_api instead of API.route_token, as normally expected by the server
- Defined in index.ts:293

withSettings

withSettings(additional_fetch_settings: Omit<RequestInit, "body">): ChildAPI
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!
Parameters
- additional_fetch_settings: Omit<RequestInit, "body">
  You may get more info at https://developer.mozilla.org/en-US/docs/Web/API/RequestInit#instance_properties
Returns ChildAPI
A special version of the API that changes how requests are done
Example
```
const controller = new AbortController() // this controller can be used to abort any request that uses its signal!
const user = await api.withSettings({signal: controller.signal}).getUser(7276846)
```
- Defined in index.ts:408

`Static`createAsync

createAsync(
    client_id: number,
    client_secret: string,
    user?: { code: string; redirect_uri: string },
    settings?: Partial<API>,
): Promise<API>
The normal way to create an API instance! Make sure to await it
Parameters
- client_id: number
  The ID of your client, which you can get on https://osu.ppy.sh/home/account/edit#oauth
- client_secret: string
  The Secret of your client, which you can get or reset on https://osu.ppy.sh/home/account/edit#oauth
- Optionaluser: { code: string; redirect_uri: string }
  If the instance is supposed to represent a user, use their Authorization Code and the Application Callback URL of your application!
  - code: string
    The code that appeared as a GET argument when they got redirected to the Application Callback URL (redirect_uri)
  - redirect_uri: string
    The Application Callback URL; Where the User has been redirected to after saying "okay" to your application doing stuff
- Optionalsettings: 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
Returns Promise<API>
A promise with an API instance
- Defined in index.ts:103

Beatmap Methods

`Readonly`getBeatmap

getBeatmap: (
this: API,
beatmap: number | Beatmap,
) => Promise<WithFailtimesOwnersMaxcomboBeatmapset> = Beatmap.getOne

Get extensive beatmap data about whichever beatmap you want!

Type declaration

- (
  this: API,
  beatmap: number | Beatmap,
  ): Promise<WithFailtimesOwnersMaxcomboBeatmapset>
- Get extensive beatmap data about whichever beatmap you want!
  Parameters
  - this: API
  - beatmap: number | Beatmap
    The beatmap or the id of the beatmap you're trying to get
  Returns Promise<WithFailtimesOwnersMaxcomboBeatmapset>

`Readonly`getBeatmapDifficultyAttributes

getBeatmapDifficultyAttributes: (
    this: API,
    beatmap: number | Beatmap,
    mods?: number | string[] | Mod[],
    ruleset?: Ruleset,
) => Promise<Beatmap.DifficultyAttributes.Any> = Beatmap.DifficultyAttributes.get

Get various data about the difficulty of a beatmap!

Type declaration

- (
      this: API,
      beatmap: number | Beatmap,
      mods?: number | string[] | Mod[],
      ruleset?: Ruleset,
  ): Promise<Beatmap.DifficultyAttributes.Any>
- Get various data about the difficulty of a beatmap!
  Parameters
  - this: API
  - beatmap: number | Beatmap
    The Beatmap in question
  - Optionalmods: 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)
  - Optionalruleset: Ruleset
    Useful to specify if the beatmap is a convert (defaults to the ruleset the beatmap was intended for)
  Returns Promise<Beatmap.DifficultyAttributes.Any>
  Remarks
  You may want to use api.getBeatmapDifficultyAttributesOsu (or Taiko or whatever) instead for better type safety

Remarks

You may want to use api.getBeatmapDifficultyAttributesOsu (or Taiko or whatever) instead for better type safety

`Readonly`getBeatmapDifficultyAttributesFruits

getBeatmapDifficultyAttributesFruits: (
    this: API,
    beatmap: number | Beatmap,
    mods?: number | string[] | Mod[],
) => Promise<Fruits> = Beatmap.DifficultyAttributes.getFruits

Get various data about the difficulty of a ctb beatmap!

Type declaration

- (
      this: API,
      beatmap: number | Beatmap,
      mods?: number | string[] | Mod[],
  ): Promise<Fruits>
- Get various data about the difficulty of a ctb beatmap!
  Parameters
  - this: API
  - beatmap: number | Beatmap
    The Beatmap in question
  - Optionalmods: 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)
  Returns Promise<Fruits>
  Remarks
  Since the pp update of 2025-03-06, no property exclusive to this Ruleset exists

Remarks

Since the pp update of 2025-03-06, no property exclusive to this Ruleset exists

`Readonly`getBeatmapDifficultyAttributesMania

getBeatmapDifficultyAttributesMania: (
    this: API,
    beatmap: number | Beatmap,
    mods?: number | string[] | Mod[],
) => Promise<Mania> = Beatmap.DifficultyAttributes.getMania

Get various data about the difficulty of a mania beatmap!

Type declaration

- (
      this: API,
      beatmap: number | Beatmap,
      mods?: number | string[] | Mod[],
  ): Promise<Mania>
- Get various data about the difficulty of a mania beatmap!
  Parameters
  - this: API
  - beatmap: number | Beatmap
    The Beatmap in question
  - Optionalmods: 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)
  Returns Promise<Mania>
  Remarks
  Since the pp update of 2025-03-06, no property exclusive to this Ruleset exists

Remarks

Since the pp update of 2025-03-06, no property exclusive to this Ruleset exists

`Readonly`getBeatmapDifficultyAttributesOsu

getBeatmapDifficultyAttributesOsu: (
    this: API,
    beatmap: number | Beatmap,
    mods?: number | string[] | Mod[],
) => Promise<Osu> = Beatmap.DifficultyAttributes.getOsu

Get various data about the difficulty of an osu! beatmap!

Type declaration

- (
      this: API,
      beatmap: number | Beatmap,
      mods?: number | string[] | Mod[],
  ): Promise<Osu>
- Get various data about the difficulty of an osu! beatmap!
  Parameters
  - this: API
  - beatmap: number | Beatmap
    The Beatmap in question
  - Optionalmods: 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)
  Returns Promise<Osu>

`Readonly`getBeatmapDifficultyAttributesTaiko

getBeatmapDifficultyAttributesTaiko: (
    this: API,
    beatmap: number | Beatmap,
    mods?: number | string[] | Mod[],
) => Promise<Taiko> = Beatmap.DifficultyAttributes.getTaiko

Get various data about the difficulty of a taiko beatmap!

Type declaration

- (
      this: API,
      beatmap: number | Beatmap,
      mods?: number | string[] | Mod[],
  ): Promise<Taiko>
- Get various data about the difficulty of a taiko beatmap!
  Parameters
  - this: API
  - beatmap: number | Beatmap
    The Beatmap in question
  - Optionalmods: 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)
  Returns Promise<Taiko>

`Readonly`getBeatmapPack

getBeatmapPack: (
    this: API,
    pack: string | Beatmap.Pack,
    legacy_only?: boolean,
) => Promise<Beatmap.Pack.WithBeatmapset> = Beatmap.Pack.getOne

Get data about a Beatmap.Pack using its tag!

Type declaration

- (
      this: API,
      pack: string | Beatmap.Pack,
      legacy_only?: boolean,
  ): Promise<Beatmap.Pack.WithBeatmapset>
- Get data about a Beatmap.Pack using its tag!
  Parameters
  - this: API
  - pack: string | Beatmap.Pack
    The Pack or the pack tag of the Pack you're trying to get
  - legacy_only: boolean = false
    Should lazer scores be excluded from the pack's user_completion_data? (defaults to false)
  Returns Promise<Beatmap.Pack.WithBeatmapset>
  Remarks
  Currently in https://osu.ppy.sh/beatmaps/packs, when hovering a pack, its URL with its tag should be preview by your browser

Remarks

Currently in https://osu.ppy.sh/beatmaps/packs, when hovering a pack, its URL with its tag should be preview by your browser

`Readonly`getBeatmapPacks

getBeatmapPacks: (
    this: API,
    type?:
        | "standard"
        | "artist"
        | "featured"
        | "tournament"
        | "loved"
        | "chart"
        | "theme",
    cursor_string?: string,
) => Promise<
    { beatmap_packs: Beatmap.Pack[]; cursor_string: null
    | string },
> = Beatmap.Pack.getMultiple

Get an Array of up to 100 Beatmap.Packs of a specific type!

Type declaration

- (
      this: API,
      type?:
          | "standard"
          | "artist"
          | "featured"
          | "tournament"
          | "loved"
          | "chart"
          | "theme",
      cursor_string?: string,
  ): Promise<{ beatmap_packs: Beatmap.Pack[]; cursor_string: null | string }>
- Get an Array of up to 100 Beatmap.Packs of a specific type!
  Parameters
  - this: API
  - type: "standard" | "artist" | "featured" | "tournament" | "loved" | "chart" | "theme" = "standard"
    The type of the BeatmapPacks (defaults to standard)
  - Optionalcursor_string: string
    Use a response's cursor_string with the same parameters to get the next "page" of results!
  Returns Promise<{ beatmap_packs: Beatmap.Pack[]; cursor_string: null | string }>

`Readonly`getBeatmaps

getBeatmaps: (
this: API,
beatmaps: (number | Beatmap)[],
) => Promise<WithFailtimesOwnersMaxcombo[]> = Beatmap.getMultiple

Get extensive beatmap data for up to 50 beatmaps at once!

Type declaration

- (
  this: API,
  beatmaps: (number | Beatmap)[],
  ): Promise<WithFailtimesOwnersMaxcombo[]>
- Get extensive beatmap data for up to 50 beatmaps at once!
  Parameters
  - this: API
  - beatmaps: (number | Beatmap)[]
    An array of beatmaps or of objects that have the id of the beatmaps you're trying to get
  Returns Promise<WithFailtimesOwnersMaxcombo[]>

`Readonly`getBeatmapScores

getBeatmapScores: (
    this: API,
    beatmap: number | Beatmap,
    config?: Beatmap.Config,
) => Promise<Score.WithUser[]> = Beatmap.getScores

Get the top scores of a beatmap!

Type declaration

- (
      this: API,
      beatmap: number | Beatmap,
      config?: Beatmap.Config,
  ): Promise<Score.WithUser[]>
- Get the top scores of a beatmap!
  Parameters
  - this: API
  - beatmap: number | Beatmap
    The Beatmap in question
  - Optionalconfig: Beatmap.Config
    Specify the score's ruleset, mods, type, prevent a lazer score from being returned
  Returns Promise<Score.WithUser[]>
  Remarks
  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

Remarks

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`getBeatmapUserScore

getBeatmapUserScore: (
    this: API,
    beatmap: number | Beatmap,
    user: number | User,
    config?: Pick<Beatmap.Config, "legacy_only" | "mods" | "ruleset">,
) => Promise<{ position: number; score: WithUserBeatmap }> = Beatmap.getUserScore

Get the score on a beatmap made by a specific user (with specific mods and on a specific ruleset if needed)

Type declaration

- (
      this: API,
      beatmap: number | Beatmap,
      user: number | User,
      config?: Pick<Beatmap.Config, "legacy_only" | "mods" | "ruleset">,
  ): Promise<{ position: number; score: WithUserBeatmap }>
- Get the score on a beatmap made by a specific user (with specific mods and on a specific ruleset if needed)
  Parameters
  - this: API
  - beatmap: number | Beatmap
    The Beatmap the score was made on
  - user: number | User
    The User who made the score
  - Optionalconfig: Pick<Beatmap.Config, "legacy_only" | "mods" | "ruleset">
    Specify the score's ruleset, the score's mods, prevent a lazer score from being returned
  Returns Promise<{ position: number; score: WithUserBeatmap }>
  An Object with the position of the score according to the specified Mods and Ruleset, and with the score itself

Returns

An Object with the position of the score according to the specified Mods and Ruleset, and with the score itself

`Readonly`getBeatmapUserScores

getBeatmapUserScores: (
    this: API,
    beatmap: number | Beatmap,
    user: number | User,
    config?: Pick<Beatmap.Config, "legacy_only" | "ruleset">,
) => Promise<Score[]> = Beatmap.getUserScores

Get the scores on a beatmap made by a specific user (with the possibility to specify if the scores are on a convert)

Type declaration

- (
      this: API,
      beatmap: number | Beatmap,
      user: number | User,
      config?: Pick<Beatmap.Config, "legacy_only" | "ruleset">,
  ): Promise<Score[]>
- Get the scores on a beatmap made by a specific user (with the possibility to specify if the scores are on a convert)
  Parameters
  - this: API
  - beatmap: number | Beatmap
    The Beatmap the scores were made on
  - user: number | User
    The User who made the scores
  - Optionalconfig: Pick<Beatmap.Config, "legacy_only" | "ruleset">
    Specify the score's ruleset, prevent a lazer score from being returned**
  Returns Promise<Score[]>

`Readonly`getBeatmapUserTags

getBeatmapUserTags: (this: API) => Promise<Beatmap.UserTag[]> = Beatmap.UserTag.getAll

Get all the UserTags that currently exist in the game!

Type declaration

- (this: API): Promise<Beatmap.UserTag[]>
- Get all the UserTags that currently exist in the game!
  Parameters
  - this: API
  Returns Promise<Beatmap.UserTag[]>
  An Array of UserTags

Returns

An Array of UserTags

`Readonly`lookupBeatmap

lookupBeatmap: (
this: API,
query: { checksum?: string; filename?: string; id?: number },
) => Promise<WithFailtimesOwnersMaxcomboBeatmapset> = Beatmap.lookup

Get extensive beatmap data about whichever beatmap you want!

Type declaration

- (
  this: API,
  query: { checksum?: string; filename?: string; id?: number },
  ): Promise<WithFailtimesOwnersMaxcomboBeatmapset>
- Get extensive beatmap data about whichever beatmap you want!
  Parameters
  - this: API
  - query: { checksum?: string; filename?: string; id?: number }
    What to specify in order to find the right beatmap
  Returns Promise<WithFailtimesOwnersMaxcomboBeatmapset>

Beatmapset Methods

`Readonly`getBeatmapset

getBeatmapset: (this: API, beatmapset: number | Beatmapset) => Promise<Plus> = Beatmapset.getOne

Get extensive beatmapset data about whichever beatmapset you want!

Type declaration

- (this: API, beatmapset: number | Beatmapset): Promise<Plus>
- Get extensive beatmapset data about whichever beatmapset you want!
  Parameters
  - this: API
  - beatmapset: number | Beatmapset
    The beatmapset or the id of the beatmapset you're trying to get
  Returns Promise<Plus>

`Readonly`getBeatmapsetDiscussionPosts

getBeatmapsetDiscussionPosts: (
    this: API,
    from?: {
        discussion?: number | Beatmapset.Discussion;
        user?: number | User;
    },
    types?: ("first" | "reply" | "system")[],
    config?: Miscellaneous.Config,
) => Promise<
    {
        beatmapsets: WithHype[];
        cursor_string: null
        | string;
        posts: Beatmapset.Discussion.Post[];
        users: User[];
    },
> = Beatmapset.Discussion.Post.getMultiple

Get complex data about the posts of a beatmapset's discussion or of a user!

Type declaration

- (
      this: API,
      from?: {
          discussion?: number | Beatmapset.Discussion;
          user?: number | User;
      },
      types?: ("first" | "reply" | "system")[],
      config?: Miscellaneous.Config,
  ): Promise<
      {
          beatmapsets: WithHype[];
          cursor_string: null
          | string;
          posts: Beatmapset.Discussion.Post[];
          users: User[];
      },
  >
- Get complex data about the posts of a beatmapset's discussion or of a user!
  Parameters
  - this: API
  - Optionalfrom: { discussion?: number | Beatmapset.Discussion; user?: number | User }
    From where/who are the posts coming from? A specific discussion, a specific user?
  - Optionaltypes: ("first" | "reply" | "system")[]
    What kind of posts?
  - Optionalconfig: Miscellaneous.Config
    How many results maximum, how to sort them, which page of those, maybe a cursor_string...
  Returns Promise<
      {
          beatmapsets: WithHype[];
          cursor_string: null
          | string;
          posts: Beatmapset.Discussion.Post[];
          users: User[];
      },
  >
  Relevant posts and info about them
  
  Remarks
  (2024-03-11) For months now, the API's documentation says the response is likely to change, so beware

Remarks

(2024-03-11) For months now, the API's documentation says the response is likely to change, so beware

Returns

Relevant posts and info about them

`Readonly`getBeatmapsetDiscussions

getBeatmapsetDiscussions: (
    this: API,
    from?: {
        beatmapset?: number | Beatmapset;
        status?:
            | "all"
            | "ranked"
            | "qualified"
            | "disqualified"
            | "never_qualified";
        user?: number
        | User;
    },
    filter?: {
        only_unresolved?: boolean;
        types?: (
            | "suggestion"
            | "problem"
            | "mapper_note"
            | "praise"
            | "hype"
            | "review"
        )[];
    },
    config?: Miscellaneous.Config,
) => Promise<
    {
        beatmaps: Beatmap.Extended[];
        beatmapsets: Beatmapset.Extended[];
        cursor_string: null
        | string;
        discussions: WithStartingpost[];
        included_discussions: WithStartingpost[];
        reviews_config: { max_blocks: number };
        users: WithGroups[];
    },
> = Beatmapset.Discussion.getMultiple

Get complex data about the discussion page of any beatmapet that you want!

Type declaration

- (
      this: API,
      from?: {
          beatmapset?: number | Beatmapset;
          status?:
              | "all"
              | "ranked"
              | "qualified"
              | "disqualified"
              | "never_qualified";
          user?: number
          | User;
      },
      filter?: {
          only_unresolved?: boolean;
          types?: (
              | "suggestion"
              | "problem"
              | "mapper_note"
              | "praise"
              | "hype"
              | "review"
          )[];
      },
      config?: Miscellaneous.Config,
  ): Promise<
      {
          beatmaps: Beatmap.Extended[];
          beatmapsets: Beatmapset.Extended[];
          cursor_string: null
          | string;
          discussions: WithStartingpost[];
          included_discussions: WithStartingpost[];
          reviews_config: { max_blocks: number };
          users: WithGroups[];
      },
  >
- Get complex data about the discussion page of any beatmapet that you want!
  Parameters
  - this: API
  - Optionalfrom: {
        beatmapset?: number | Beatmapset;
        status?:
            | "all"
            | "ranked"
            | "qualified"
            | "disqualified"
            | "never_qualified";
        user?: number
        | User;
    }
    From where/who are the discussions coming from? Maybe only qualified sets?
  - Optionalfilter: {
        only_unresolved?: boolean;
        types?: (
            "suggestion"
            | "problem"
            | "mapper_note"
            | "praise"
            | "hype"
            | "review"
        )[];
    }
    Should those discussions only be unresolved problems, for example?
  - Optionalconfig: Miscellaneous.Config
    How many results maximum, how to sort them, which page of those, maybe a cursor_string...
  Returns Promise<
      {
          beatmaps: Beatmap.Extended[];
          beatmapsets: Beatmapset.Extended[];
          cursor_string: null
          | string;
          discussions: WithStartingpost[];
          included_discussions: WithStartingpost[];
          reviews_config: { max_blocks: number };
          users: WithGroups[];
      },
  >
  Relevant discussions and info about them
  
  Remarks
  (2024-03-11) For months now, the API's documentation says the response is likely to change, so beware

Remarks

(2024-03-11) For months now, the API's documentation says the response is likely to change, so beware

Returns

Relevant discussions and info about them

`Readonly`getBeatmapsetDiscussionVotes

getBeatmapsetDiscussionVotes: (
    this: API,
    from?: {
        discussion?: number | Beatmapset.Discussion;
        vote_giver?: number | User;
        vote_receiver?: number | User;
    },
    score?: 1 | -1,
    config?: Miscellaneous.Config,
) => Promise<
    {
        cursor_string: null
        | string;
        discussions: Beatmapset.Discussion[];
        users: WithGroups[];
        votes: Beatmapset.Discussion.Vote[];
    },
> = Beatmapset.Discussion.Vote.getMultiple

Get complex data about the votes of a beatmapset's discussions or/and received/given by a specific user!

Type declaration

- (
      this: API,
      from?: {
          discussion?: number | Beatmapset.Discussion;
          vote_giver?: number | User;
          vote_receiver?: number | User;
      },
      score?: 1 | -1,
      config?: Miscellaneous.Config,
  ): Promise<
      {
          cursor_string: null
          | string;
          discussions: Beatmapset.Discussion[];
          users: WithGroups[];
          votes: Beatmapset.Discussion.Vote[];
      },
  >
- Get complex data about the votes of a beatmapset's discussions or/and received/given by a specific user!
  Parameters
  - this: API
  - Optionalfrom: {
        discussion?: number | Beatmapset.Discussion;
        vote_giver?: number | User;
        vote_receiver?: number | User;
    }
    The discussion with the votes, the user who voted, the user who's gotten the votes...
  - Optionalscore: 1 | -1
    An upvote (1) or a downvote (-1)
  - Optionalconfig: Miscellaneous.Config
    How many results maximum, how to sort them, which page of those, maybe a cursor_string...
  Returns Promise<
      {
          cursor_string: null
          | string;
          discussions: Beatmapset.Discussion[];
          users: WithGroups[];
          votes: Beatmapset.Discussion.Vote[];
      },
  >
  Relevant votes and info about them
  
  Remarks
  (2024-03-11) For months now, the API's documentation says the response is likely to change, so beware

Remarks

(2024-03-11) For months now, the API's documentation says the response is likely to change, so beware

Returns

Relevant votes and info about them

`Readonly`getBeatmapsetEvents

getBeatmapsetEvents: (
    this: API,
    from?: {
        beatmapset?: number | Beatmapset;
        max_date?: Date;
        min_date?: Date;
        user?: number | User;
    },
    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"
    )[],
    config?: Miscellaneous.Config,
) => Promise<{ events: Beatmapset.Event.Any[]; users: WithGroups[] }> = Beatmapset.Event.getMultiple

Get complex data about the events of a beatmapset and the users involved with them!

Type declaration

- (
      this: API,
      from?: {
          beatmapset?: number | Beatmapset;
          max_date?: Date;
          min_date?: Date;
          user?: number | User;
      },
      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"
      )[],
      config?: Miscellaneous.Config,
  ): Promise<{ events: Beatmapset.Event.Any[]; users: WithGroups[] }>
- Get complex data about the events of a beatmapset and the users involved with them!
  Parameters
  - this: API
  - Optionalfrom: {
        beatmapset?: number | Beatmapset;
        max_date?: Date;
        min_date?: Date;
        user?: number | User;
    }
    Which beatmapset, or caused by which user? When?
  - Optionaltypes: (
        | "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"
    )[]
    What kinds of events?
  - Optionalconfig: Miscellaneous.Config
    How many results maximum, how to sort them, which page of those, maybe a cursor_string...
  Returns Promise<{ events: Beatmapset.Event.Any[]; users: WithGroups[] }>
  Relevant events and users
  
  Remarks
  This route is undocumented in the API docs, so this is only the result of my interpretation of the website's code and could be unstable

Remarks

This route is undocumented in the API docs, so this is only the result of my interpretation of the website's code and could be unstable

Returns

Relevant events and users

`Readonly`lookupBeatmapset

lookupBeatmapset: (this: API, beatmap: number | Beatmap) => Promise<Plus> = Beatmapset.lookup

Get extensive data about a beatmapset by using a beatmap!

Type declaration

- (this: API, beatmap: number | Beatmap): Promise<Plus>
- Get extensive data about a beatmapset by using a beatmap!
  Parameters
  - this: API
  - beatmap: number | Beatmap
    A beatmap from the beatmapset you're looking for
  Returns Promise<Plus>

`Readonly`searchBeatmapsets

searchBeatmapsets: (
    this: API,
    query?: {
        categories?:
            | "Graveyard"
            | "Pending"
            | "Ranked"
            | "Qualified"
            | "Loved"
            | "Any"
            | "Favourites"
            | "WIP"
            | "My Maps";
        cursor_string?: string;
        extra?: ("must_have_video" | "must_have_storyboard")[];
        general?: (
            | "Recommended difficulty"
            | "Include converted beatmaps"
            | "Subscribed mappers"
            | "Spotlighted beatmaps"
            | "Featured Artists"
        )[];
        genre?: | Unspecified
        | any[any]
        | Anime
        | Rock
        | Pop
        | Other
        | Novelty
        | any[any]
        | Electronic
        | Metal
        | Classical
        | Folk
        | Jazz;
        hide_explicit_content?: true;
        keywords?: string;
        language?: | Unspecified
        | English
        | Japanese
        | Chinese
        | Instrumental
        | Korean
        | French
        | German
        | Swedish
        | Spanish
        | Italian
        | Russian
        | Polish
        | Other;
        mode?: Ruleset;
        played?: "Played"
        | "Unplayed";
        rank_achieved?: (
            "Silver SS"
            | "SS"
            | "Silver S"
            | "S"
            | "A"
            | "B"
            | "C"
            | "D"
        )[];
        sort?: {
            by:
                | "artist"
                | "title"
                | "ranked"
                | "difficulty"
                | "rating"
                | "plays"
                | "favourites"
                | "updated";
            in: "asc"
            | "desc";
        };
    },
) => Promise<
    {
        beatmapsets: WithBeatmapPacktags[];
        cursor_string: null
        | string;
        error: any;
        recommended_difficulty: null | number;
        total: number;
    },
> = Beatmapset.search

Search for beatmapsets as if you were on the website or on lazer!

Type declaration

- (
      this: API,
      query?: {
          categories?:
              | "Graveyard"
              | "Pending"
              | "Ranked"
              | "Qualified"
              | "Loved"
              | "Any"
              | "Favourites"
              | "WIP"
              | "My Maps";
          cursor_string?: string;
          extra?: ("must_have_video" | "must_have_storyboard")[];
          general?: (
              | "Recommended difficulty"
              | "Include converted beatmaps"
              | "Subscribed mappers"
              | "Spotlighted beatmaps"
              | "Featured Artists"
          )[];
          genre?: | Unspecified
          | any[any]
          | Anime
          | Rock
          | Pop
          | Other
          | Novelty
          | any[any]
          | Electronic
          | Metal
          | Classical
          | Folk
          | Jazz;
          hide_explicit_content?: true;
          keywords?: string;
          language?: | Unspecified
          | English
          | Japanese
          | Chinese
          | Instrumental
          | Korean
          | French
          | German
          | Swedish
          | Spanish
          | Italian
          | Russian
          | Polish
          | Other;
          mode?: Ruleset;
          played?: "Played"
          | "Unplayed";
          rank_achieved?: (
              "Silver SS"
              | "SS"
              | "Silver S"
              | "S"
              | "A"
              | "B"
              | "C"
              | "D"
          )[];
          sort?: {
              by:
                  | "artist"
                  | "title"
                  | "ranked"
                  | "difficulty"
                  | "rating"
                  | "plays"
                  | "favourites"
                  | "updated";
              in: "asc"
              | "desc";
          };
      },
  ): Promise<
      {
          beatmapsets: WithBeatmapPacktags[];
          cursor_string: null
          | string;
          error: any;
          recommended_difficulty: null | number;
          total: number;
      },
  >
- Search for beatmapsets as if you were on the website or on lazer!
  Parameters
  - this: API
  - Optionalquery: {
        categories?:
            | "Graveyard"
            | "Pending"
            | "Ranked"
            | "Qualified"
            | "Loved"
            | "Any"
            | "Favourites"
            | "WIP"
            | "My Maps";
        cursor_string?: string;
        extra?: ("must_have_video" | "must_have_storyboard")[];
        general?: (
            | "Recommended difficulty"
            | "Include converted beatmaps"
            | "Subscribed mappers"
            | "Spotlighted beatmaps"
            | "Featured Artists"
        )[];
        genre?: | Unspecified
        | any[any]
        | Anime
        | Rock
        | Pop
        | Other
        | Novelty
        | any[any]
        | Electronic
        | Metal
        | Classical
        | Folk
        | Jazz;
        hide_explicit_content?: true;
        keywords?: string;
        language?: | Unspecified
        | English
        | Japanese
        | Chinese
        | Instrumental
        | Korean
        | French
        | German
        | Swedish
        | Spanish
        | Italian
        | Russian
        | Polish
        | Other;
        mode?: Ruleset;
        played?: "Played"
        | "Unplayed";
        rank_achieved?: (
            "Silver SS"
            | "SS"
            | "Silver S"
            | "S"
            | "A"
            | "B"
            | "C"
            | "D"
        )[];
        sort?: {
            by:
                | "artist"
                | "title"
                | "ranked"
                | "difficulty"
                | "rating"
                | "plays"
                | "favourites"
                | "updated";
            in: "asc"
            | "desc";
        };
    }
    All the filters and sorting options that you'd normally find on the website or on lazer
    - Optionalcategories?:
          | "Graveyard"
          | "Pending"
          | "Ranked"
          | "Qualified"
          | "Loved"
          | "Any"
          | "Favourites"
          | "WIP"
          | "My Maps"
      Filter in sets depending on their status or on their relation with the authorized user (defaults to all that have a leaderboard)
    - Optionalcursor_string?: string
      The thing you've got from a previous request to get another page of results!
    - Optionalextra?: ("must_have_video" | "must_have_storyboard")[]
      Should all sets have a video, a storyboard, maybe both at once?
    - Optionalgeneral?: (
          | "Recommended difficulty"
          | "Include converted beatmaps"
          | "Subscribed mappers"
          | "Spotlighted beatmaps"
          | "Featured Artists"
      )[]
      Various filters to activate
    - Optionalgenre?:
          | Unspecified
          | any[any]
          | Anime
          | Rock
          | Pop
          | Other
          | Novelty
          | any[any]
          | Electronic
          | Metal
          | Classical
          | Folk
          | Jazz
      Specify the musical genre of the music of the beatmapsets you're searching for (don't specify to get any genre)
      
      Remarks
      "Any"/0 actually looks up sets that specifically have the Genre "Any" such as 5947, it's excluded because it's counter-intuitive and near useless (but you can do something like 1-1 if you actually want that!)
    - Optionalhide_explicit_content?: true
      Use this to hide all sets that are marked as explicit
    - Optionalkeywords?: string
      What you'd put in the searchbar, like the name of a beatmapset or a mapper!
    - Optionallanguage?:
          | Unspecified
          | English
          | Japanese
          | Chinese
          | Instrumental
          | Korean
          | French
          | German
          | Swedish
          | Spanish
          | Italian
          | Russian
          | Polish
          | Other
      Specify the spoken language of the music of the beatmapsets you're searching for (don't specify to get any language)
      
      Remarks
      "Any"/0 actually looks up sets that specifically have the Language "Any" (and no set has that), it's excluded because it's counter-intuitive and near useless (but you can do something like 1-1 if you actually want that!)
    - Optionalmode?: Ruleset
      Only get sets that have maps that you can play in the ruleset of your choice
    - Optionalplayed?: "Played" | "Unplayed"
      Does the authorized user with osu!supporter have already played those sets, or have they not played them yet?
    - Optionalrank_achieved?: ("Silver SS" | "SS" | "Silver S" | "S" | "A" | "B" | "C" | "D")[]
      Does the authorized user with osu!supporter have already achieved certain ranks on those sets?
    - Optionalsort?: {
          by:
              | "artist"
              | "title"
              | "ranked"
              | "difficulty"
              | "rating"
              | "plays"
              | "favourites"
              | "updated";
          in: "asc"
          | "desc";
      }
      Sort by what, in ascending/descending order
  Returns Promise<
      {
          beatmapsets: WithBeatmapPacktags[];
          cursor_string: null
          | string;
          error: any;
          recommended_difficulty: null | number;
          total: number;
      },
  >
  Relevant Beatmapsets that contain Beatmaps, and a cursor_string to allow you to look for more of the same!
  
  Remarks
  This does not bypass the current osu!supporter requirement for certain filters

Remarks

This does not bypass the current osu!supporter requirement for certain filters

Returns

Relevant Beatmapsets that contain Beatmaps, and a cursor_string to allow you to look for more of the same!

Changelog Methods

`Readonly`getChangelogBuild

getChangelogBuild: (
    this: API,
    stream: string,
    build: string,
) => Promise<WithChangelogentriesVersions> = Changelog.Build.getOne

Get details about the version/update/build of something related to osu!

Type declaration

- (
      this: API,
      stream: string,
      build: string,
  ): Promise<WithChangelogentriesVersions>
- Get details about the version/update/build of something related to osu!
  Parameters
  - this: API
  - stream: string
    The name of the thing related to osu!, like lazer, web, cuttingedge, beta40, stable40
  - build: string
    The name of the version! Usually something like 2023.1026.0 for lazer, or 20230326 for stable
  Returns Promise<WithChangelogentriesVersions>

`Readonly`getChangelogBuilds

getChangelogBuilds: (
    this: API,
    stream?: string,
    range?: { from?: string; to?: string | number },
    message_formats?: ("html" | "markdown")[],
) => Promise<WithUpdatestreamsChangelogentries[]> = Changelog.Build.getMultiple

Get up to 21 versions/updates/builds!

Type declaration

- (
      this: API,
      stream?: string,
      range?: { from?: string; to?: string | number },
      message_formats?: ("html" | "markdown")[],
  ): Promise<WithUpdatestreamsChangelogentries[]>
- Get up to 21 versions/updates/builds!
  Parameters
  - this: API
  - Optionalstream: string
    Only get builds from a specific stream
  - Optionalrange: { from?: string; to?: string | number }
    Get builds that were released before/after (and including) those builds
    - Optionalfrom?: string
      The name of the build
    - Optionalto?: string | number
      The name or the id of the build
  - message_formats: ("html" | "markdown")[] = ...
    changelog_entries will have a message property if markdown, message_html property if html (defaults to both)
  Returns Promise<WithUpdatestreamsChangelogentries[]>

`Readonly`getChangelogStreams

getChangelogStreams: (this: API) => Promise<WithLatestbuildUsercount[]> = Changelog.UpdateStream.getAll

An effective way to get all available streams, as well as their latest version!

Type declaration

- (this: API): Promise<WithLatestbuildUsercount[]>
- An effective way to get all available streams, as well as their latest version!
  Parameters
  - this: API
  Returns Promise<WithLatestbuildUsercount[]>
  Example
```
const names_of_streams = (await api.getChangelogStreams()).map(s => s.name)
```

`Readonly`lookupChangelogBuild

lookupChangelogBuild: (
    this: API,
    changelog: string | number,
    message_formats?: ("html" | "markdown")[],
) => Promise<WithChangelogentriesVersions> = Changelog.Build.lookup

Get details about the version/update/build of something related to osu!

Type declaration

- (
      this: API,
      changelog: string | number,
      message_formats?: ("html" | "markdown")[],
  ): Promise<WithChangelogentriesVersions>
- Get details about the version/update/build of something related to osu!
  Parameters
  - this: API
  - changelog: string | number
    A stream name like lazer, a build version like 2023.1026.0, or the id of a build
  - message_formats: ("html" | "markdown")[] = ...
    changelog_entries will have a message property if markdown, message_html property if html (defaults to both)
  Returns Promise<WithChangelogentriesVersions>

Chat Methods

`Readonly`createChatAnnouncementChannel

createChatAnnouncementChannel: (
    this: API,
    channel: { description: string; name: string },
    user_targets: (number | User)[],
    message: string,
) => Promise<Chat.Channel> = Chat.Channel.createAnnouncement

Create a new announcement!

Type declaration

- (
      this: API,
      channel: { description: string; name: string },
      user_targets: (number | User)[],
      message: string,
  ): Promise<Chat.Channel>
- Create a new announcement!
  Parameters
  - this: API
  - channel: { description: string; name: string }
    Details of the channel you're creating
  - user_targets: (number | User)[]
    The people that will receive your message
  - message: string
    The message to send with the announcement
  Returns Promise<Chat.Channel>
  The newly created channel!
  
  Scope
  "chat.write_manage"
  
  Remarks
  From my understanding, this WILL 403 unless the user is kinda special

Remarks

From my understanding, this WILL 403 unless the user is kinda special

Returns

The newly created channel!

`Readonly`createChatPrivateChannel

createChatPrivateChannel: (
this: API,
user_target: number | User,
) => Promise<WithRecentmessages> = Chat.Channel.createPrivate

Create/Open/Join a private messages chat channel!

Type declaration

- (this: API, user_target: number | User): Promise<WithRecentmessages>
- Create/Open/Join a private messages chat channel!
  Parameters
  - this: API
  - user_target: number | User
    The other user able to read and send messages in this channel
  Returns Promise<WithRecentmessages>
  The newly created channel!
  
  Scope
  "chat.read"

Returns

The newly created channel!

`Readonly`generateChatWebsocket

generateChatWebsocket: (
    this: API,
    headers?: { [key: string]: any },
    server?: string,
) => WebSocket = Chat.Websocket.generate

Get a WebSocket to get Websocket events from!

Type declaration

- (this: API, headers?: { [key: string]: any }, server?: string): WebSocket
- Get a WebSocket to get Websocket events from!
  Parameters
  - this: API
  - Optionalheaders: { [key: string]: any }
    The headers that will be used to create the WebSocket (defaults to running getChatWebsocketHeaders())
  - server: string = "wss://notify.ppy.sh"
    The "notification websocket/server" URL (defaults to wss://notify.ppy.sh)
  Returns WebSocket

`Readonly`getChatChannel

getChatChannel: (
this: API,
channel: number | Chat.Channel,
) => Promise<WithDetails> = Chat.Channel.getOne

Get a ChatChannel that you have joined, and the users in it if it is a private channel!

Type declaration

- (this: API, channel: number | Chat.Channel): Promise<WithDetails>
- Get a ChatChannel that you have joined, and the users in it if it is a private channel!
  Parameters
  - this: API
  - channel: number | Chat.Channel
    The channel in question
  Returns Promise<WithDetails>
  Scope
  "chat.read"
  
  Remarks
  Will 404 if the user has not joined the channel (use joinChatChannel for that)

Remarks

Will 404 if the user has not joined the channel (use joinChatChannel for that)

`Readonly`getChatChannels

getChatChannels: (this: API) => Promise<Chat.Channel[]> = Chat.Channel.getAll

Get a list of all publicly joinable channels!

Type declaration

- (this: API): Promise<Chat.Channel[]>
- Get a list of all publicly joinable channels!
  Parameters
  - this: API
  Returns Promise<Chat.Channel[]>
  Scope
  "chat.read"

`Readonly`getChatMessages

getChatMessages: (
    this: API,
    channel: number | Chat.Channel,
    limit?: number,
    since?: number | Chat.Message,
    until?: number | Chat.Message,
) => Promise<WithSender[]> = Chat.Message.getMultiple

Get the recent messages of a specific ChatChannel!

Type declaration

- (
      this: API,
      channel: number | Chat.Channel,
      limit?: number,
      since?: number | Chat.Message,
      until?: number | Chat.Message,
  ): Promise<WithSender[]>
- Get the recent messages of a specific ChatChannel!
  Parameters
  - this: API
  - channel: number | Chat.Channel
    The Channel you wanna get the messages from
  - limit: number = 20
    The maximum amount of messages you want to get, up to 50! (defaults to 20)
  - Optionalsince: number | Chat.Message
    Get the messages sent after this message
  - Optionaluntil: number | Chat.Message
    Get the messages sent up to but not including this message
  Returns Promise<WithSender[]>
  Scope
  "chat.read"

`Readonly`getChatWebsocketHeaders

getChatWebsocketHeaders: (this: API) => { [key: string]: any } = Chat.Websocket.getHeaders

Get the headers you might require in order to create a WebSocket connection!

Type declaration

- (this: API): { [key: string]: any }
- Get the headers you might require in order to create a WebSocket connection!
  Parameters
  - this: API
  Returns { [key: string]: any }
  An object with the proper Authorization: Bearer header, in addition to the headers used in other requests, which are all specified in API.headers
  
  Remarks
  Feel free to use this and ignore API.generateChatWebsocket if for example you're gonna use a third party package for handling websockets

Remarks

Feel free to use this and ignore API.generateChatWebsocket if for example you're gonna use a third party package for handling websockets

Returns

An object with the proper Authorization: Bearer header, in addition to the headers used in other requests, which are all specified in API.headers

`Readonly`joinChatChannel

joinChatChannel: (
    this: API,
    channel: number | Chat.Channel,
    user?: number | User,
) => Promise<WithDetails> = Chat.Channel.joinOne

Join a public or multiplayer ChatChannel, allowing you to interact with it!

Type declaration

- (
      this: API,
      channel: number | Chat.Channel,
      user?: number | User,
  ): Promise<WithDetails>
- Join a public or multiplayer ChatChannel, allowing you to interact with it!
  Parameters
  - this: API
  - channel: number | Chat.Channel
    The channel you wanna join
  - Optionaluser: number | User
    The user joining the channel (defaults to the presumed authorized user (api.user))
  Returns Promise<WithDetails>
  Scope
  "chat.write_manage"

`Readonly`keepChatAlive

keepChatAlive: (
    this: API,
    since?: {
        message?: number | Chat.Message;
        user_silence?: number | UserSilence;
    },
) => Promise<UserSilence[]> = Chat.keepAlive

Needs to be done periodically to reset chat activity timeout

Type declaration

- (
      this: API,
      since?: {
          message?: number | Chat.Message;
          user_silence?: number | UserSilence;
      },
  ): Promise<UserSilence[]>
- Needs to be done periodically to reset chat activity timeout
  Parameters
  - this: API
  - Optionalsince: { message?: number | Chat.Message; user_silence?: number | UserSilence }
    UserSilences that are before that will not be returned!
  Returns Promise<UserSilence[]>
  A list of recent silences
  
  Scope
  "chat.read"
  
  Remarks
  Every 30 seconds is a good idea

Remarks

Every 30 seconds is a good idea

Returns

A list of recent silences

`Readonly`leaveChatChannel

leaveChatChannel: (
    this: API,
    channel: number | Chat.Channel,
    user?: number | User,
) => Promise<void> = Chat.Channel.leaveOne

Leave/Close a public ChatChannel!

Type declaration

- (this: API, channel: number | Chat.Channel, user?: number | User): Promise<void>
- Leave/Close a public ChatChannel!
  Parameters
  - this: API
  - channel: number | Chat.Channel
    The channel you wanna leave/close
  - Optionaluser: number | User
    The user leaving/closing the channel (defaults to the presumed authorized user (api.user))
  Returns Promise<void>
  Scope
  "chat.write_manage"

`Readonly`markChatChannelAsRead

markChatChannelAsRead: (
    this: API,
    channel: number | Chat.Channel,
    message: number | Chat.Message,
) => Promise<void> = Chat.Channel.markAsRead

Mark a certain channel as read up to a given message!

Type declaration

- (
      this: API,
      channel: number | Chat.Channel,
      message: number | Chat.Message,
  ): Promise<void>
- Mark a certain channel as read up to a given message!
  Parameters
  - this: API
  - channel: number | Chat.Channel
    The channel in question
  - message: number | Chat.Message
    You're marking this and all the messages before it as read!
  Returns Promise<void>
  Scope
  "chat.read"

`Readonly`sendChatMessage

sendChatMessage: (
    this: API,
    channel: number | Chat.Channel,
    message: string,
    is_action?: boolean,
) => Promise<WithSender> = Chat.Message.send

Send a message in a ChatChannel!

Type declaration

- (
      this: API,
      channel: number | Chat.Channel,
      message: string,
      is_action?: boolean,
  ): Promise<WithSender>
- Send a message in a ChatChannel!
  Parameters
  - this: API
  - channel: number | Chat.Channel
    The channel in which you want to send your message
  - message: string
    The message you wanna send
  - is_action: boolean = false
    Is it a command? Like /me dances (defaults to false)
  Returns Promise<WithSender>
  The newly sent ChatMessage!
  
  Scope
  "chat.write"

Returns

The newly sent ChatMessage!

`Readonly`sendChatPrivateMessage

sendChatPrivateMessage: (
    this: API,
    user_target: number | User,
    message: string,
    is_action?: boolean,
    uuid?: string,
) => Promise<{ channel: Chat.Channel; message: WithSender }> = Chat.Message.sendPrivate

Send a private message to someone!

Type declaration

- (
      this: API,
      user_target: number | User,
      message: string,
      is_action?: boolean,
      uuid?: string,
  ): Promise<{ channel: Chat.Channel; message: WithSender }>
- Send a private message to someone!
  Parameters
  - this: API
  - user_target: number | User
    The User you wanna send your message to!
  - message: string
    The message you wanna send
  - is_action: boolean = false
    Is it a command? Like /me dances (defaults to false)
  - Optionaluuid: string
    A client-side message identifier
  Returns Promise<{ channel: Chat.Channel; message: WithSender }>
  The message you sent
  
  Scope
  "chat.write"
  
  Remarks
  You don't need to use createChatPrivateChannel before sending a message

Remarks

You don't need to use createChatPrivateChannel before sending a message

Returns

The message you sent

Comment Methods

`Readonly`getComment

getComment: (this: API, comment: number | Comment) => Promise<Comment.Bundle> = Comment.getOne

Get a specific comment by using its id!

Type declaration

- (this: API, comment: number | Comment): Promise<Comment.Bundle>
- Get a specific comment by using its id!
  Parameters
  - this: API
  - comment: number | Comment
    The comment in question
  Returns Promise<Comment.Bundle>

`Readonly`getComments

getComments: (
    this: API,
    from?: { id: number; type: "beatmapset" | "build" | "news_post" },
    parent?: number | Comment,
    sort?: {
        after?: number | Comment;
        cursor?: null | { created_at: Date; id: number };
        type?: "new" | "old" | "top";
    },
) => Promise<WithTotalToplevelcount> = Comment.getMultiple

Get comments that meet any of your requirements!

Type declaration

- (
      this: API,
      from?: { id: number; type: "beatmapset" | "build" | "news_post" },
      parent?: number | Comment,
      sort?: {
          after?: number | Comment;
          cursor?: null | { created_at: Date; id: number };
          type?: "new" | "old" | "top";
      },
  ): Promise<WithTotalToplevelcount>
- Get comments that meet any of your requirements!
  Parameters
  - this: API
  - Optionalfrom: { id: number; type: "beatmapset" | "build" | "news_post" }
    From where are the comments coming from? Maybe a beatmapset, but then, which beatmapset?
  - Optionalparent: number | Comment
    The comments are replying to which comment? Make the id 0 to filter out replies (and only get top level comments)
  - Optionalsort: {
        after?: number | Comment;
        cursor?: null | { created_at: Date; id: number };
        type?: "new" | "old" | "top";
    }
    Should the comments be sorted by votes? Should they be from after a certain date? Maybe you can give a cursor?
  Returns Promise<WithTotalToplevelcount>

Event Methods

`Readonly`getEvents

getEvents: (
this: API,
config?: Pick<Miscellaneous.Config, "sort" | "cursor_string">,
) => Promise<{ cursor_string: null | string; events: Event.Any[] }> = Event.getMultiple

Get everything note-worthy that happened on osu! recently!

Type declaration

- (
  this: API,
  config?: Pick<Miscellaneous.Config, "sort" | "cursor_string">,
  ): Promise<{ cursor_string: null | string; events: Event.Any[] }>
- Get everything note-worthy that happened on osu! recently!
  Parameters
  - this: API
  - Optionalconfig: Pick<Miscellaneous.Config, "sort" | "cursor_string">
    Sort the results differently, or use a cursor_string to get more results
  Returns Promise<{ cursor_string: null | string; events: Event.Any[] }>

Forum Methods

`Readonly`createForumTopic

createForumTopic: (
    this: API,
    forum: number | Forum,
    title: string,
    text: string,
    poll?: {
        hide_results?: boolean;
        length_days: number;
        max_options?: number;
        options: string[];
        title: string;
        vote_change?: boolean;
    },
) => Promise<{ post: Forum.Post; topic: Forum.Topic }> = Forum.Topic.create

Create a new Forum.Topic in the forum of your choice!

Type declaration

- (
      this: API,
      forum: number | Forum,
      title: string,
      text: string,
      poll?: {
          hide_results?: boolean;
          length_days: number;
          max_options?: number;
          options: string[];
          title: string;
          vote_change?: boolean;
      },
  ): Promise<{ post: Forum.Post; topic: Forum.Topic }>
- Create a new Forum.Topic in the forum of your choice!
  Parameters
  - this: API
  - forum: number | Forum
    The Forum you're creating your topic in
  - title: string
    The topic's title
  - text: string
    The first post's content/message
  - Optionalpoll: {
        hide_results?: boolean;
        length_days: number;
        max_options?: number;
        options: string[];
        title: string;
        vote_change?: boolean;
    }
    If you want to make a poll, specify the parameters of that poll!
    - Optionalhide_results?: boolean
      Should the results of the poll be hidden while the voting period is still active? (defaults to false)
    - length_days: number
      Length of voting period in days, 0 means forever
    - Optionalmax_options?: number
      The maximum amount of votes per user! (defaults to 1)
    - options: string[]
      The things the users can vote for
    - title: string
    - Optionalvote_change?: boolean
      Do you allow users to change their vote? (defaults to false)
  Returns Promise<{ post: Forum.Post; topic: Forum.Topic }>
  An object with the topic you've made, and its first initial post (which uses your text)
  
  Scope
  "forum.write"
  
  Remarks
  Some users may not be allowed to do that, such as newly registered users, so this can 403 even with the right scopes

Remarks

Some users may not be allowed to do that, such as newly registered users, so this can 403 even with the right scopes

Returns

An object with the topic you've made, and its first initial post (which uses your text)

`Readonly`editForumPost

editForumPost: (
    this: API,
    post: number | Forum.Post,
    new_text: string,
) => Promise<Forum.Post> = Forum.Post.edit

Edit a ForumPost! Note that it can be the initial one of a ForumTopic!

Type declaration

- (this: API, post: number | Forum.Post, new_text: string): Promise<Forum.Post>
- Edit a ForumPost! Note that it can be the initial one of a ForumTopic!
  Parameters
  - this: API
  - post: number | Forum.Post
    The post or the id of the post in question
  - new_text: string
    The new content of the post (replaces the old content)
  Returns Promise<Forum.Post>
  The edited ForumPost
  
  Scope
  "forum.write"

Returns

The edited ForumPost

`Readonly`editForumTopicTitle

editForumTopicTitle: (
    this: API,
    topic: number | Forum.Topic,
    new_title: string,
) => Promise<Forum.Topic> = Forum.Topic.editTitle

Edit the title of a Forum.Topic!

Type declaration

- (
      this: API,
      topic: number | Forum.Topic,
      new_title: string,
  ): Promise<Forum.Topic>
- Edit the title of a Forum.Topic!
  Parameters
  - this: API
  - topic: number | Forum.Topic
    The topic or the id of the topic in question
  - new_title: string
    The new title of the topic
  Returns Promise<Forum.Topic>
  The edited ForumTopic
  
  Scope
  "forum.write"
  
  Remarks
  Use editForumPost if you wanna edit the post at the top of the topic

Remarks

Use editForumPost if you wanna edit the post at the top of the topic

Returns

The edited ForumTopic

`Readonly`getForum

getForum: (
    this: API,
    forum: number | Forum,
) => Promise<
    {
        forum: WithSubforums2;
        pinned_topics: Forum.Topic[];
        topics: Forum.Topic[];
    },
> = Forum.getOne

Get a Forum with a specific id, as well as its Forum.Topics!

Type declaration

- (
      this: API,
      forum: number | Forum,
  ): Promise<
      {
          forum: WithSubforums2;
          pinned_topics: Forum.Topic[];
          topics: Forum.Topic[];
      },
  >
- Get a Forum with a specific id, as well as its Forum.Topics!
  Parameters
  - this: API
  - forum: number | Forum
    The Forum you want to get
  Returns Promise<
      {
          forum: WithSubforums2;
          pinned_topics: Forum.Topic[];
          topics: Forum.Topic[];
      },
  >
  An object with the Forum, its topics, and the topics pinned in it

Returns

An object with the Forum, its topics, and the topics pinned in it

`Readonly`getForums

getForums: (this: API) => Promise<WithSubforums2[]> = Forum.getMultiple

Get a list of all top-level Forums!

Type declaration

- (this: API): Promise<WithSubforums2[]>
- Get a list of all top-level Forums!
  Parameters
  - this: API
  Returns Promise<WithSubforums2[]>
  All the top-level forums
  
  Remarks
  The subforums of a forum are in the properties of their respective forum

Remarks

The subforums of a forum are in the properties of their respective forum

Returns

All the top-level forums

`Readonly`getForumTopic

getForumTopic: (
    this: API,
    topic: number | Forum.Topic,
    config?: Pick<Miscellaneous.Config, "sort" | "cursor_string" | "limit"> & {
        first_post?: number | Forum.Post;
    },
) => Promise<
    {
        cursor_string: null
        | string;
        posts: Forum.Post[];
        topic: Forum.Topic;
    },
> = Forum.Topic.getOne

Get a Forum.Topic, as well as its main post (content) and the posts that were sent in it!

Type declaration

- (
      this: API,
      topic: number | Forum.Topic,
      config?: Pick<Miscellaneous.Config, "sort" | "cursor_string" | "limit"> & {
          first_post?: number | Forum.Post;
      },
  ): Promise<
      {
          cursor_string: null
          | string;
          posts: Forum.Post[];
          topic: Forum.Topic;
      },
  >
- Get a Forum.Topic, as well as its main post (content) and the posts that were sent in it!
  Parameters
  - this: API
  - topic: number | Forum.Topic
    An object with the id of the topic in question
  - Optionalconfig: Pick<Miscellaneous.Config, "sort" | "cursor_string" | "limit"> & {
    first_post?: number | Forum.Post;
    }
    How many results maximum, how to sort them, etc...
    - Optionalfirst_post?: number | Forum.Post
      The id (or the post itself) of the first post to be returned in posts (irrelevant if using a cursor_string)
  Returns Promise<
      {
          cursor_string: null
          | string;
          posts: Forum.Post[];
          topic: Forum.Topic;
      },
  >
  Remarks
  The oldest post of a topic is the text of a topic

Remarks

The oldest post of a topic is the text of a topic

`Readonly`getForumTopics

getForumTopics: (
    this: API,
    config?: Pick<Miscellaneous.Config, "sort" | "cursor_string" | "limit"> & {
        forum?: number | Forum;
    },
) => Promise<{ cursor_string: null | string; topics: Forum.Topic[] }> = Forum.Topic.getMultiple

Get multiple existing Forum.Topic, optionally in a specific Forum!

Type declaration

- (
      this: API,
      config?: Pick<Miscellaneous.Config, "sort" | "cursor_string" | "limit"> & {
          forum?: number | Forum;
      },
  ): Promise<{ cursor_string: null | string; topics: Forum.Topic[] }>
- Get multiple existing Forum.Topic, optionally in a specific Forum!
  Parameters
  - this: API
  - Optionalconfig: Pick<Miscellaneous.Config, "sort" | "cursor_string" | "limit"> & {
    forum?: number | Forum;
    }
    Specify the Forum of the Topics, sorting options, how many Topics maximum...
    - Optionalforum?: number | Forum
      From which specific Forum to get the topcis from
  Returns Promise<{ cursor_string: null | string; topics: Forum.Topic[] }>
  An object with an array of relevant Forum.Topic, and a cursor_string to allow you to go further

Returns

An object with an array of relevant Forum.Topic, and a cursor_string to allow you to go further

`Readonly`replyForumTopic

replyForumTopic: (
    this: API,
    topic: number | Forum.Topic,
    text: string,
) => Promise<Forum.Post> = Forum.Topic.reply

Make and send a Forum.Post in a Forum.Topic!

Type declaration

- (this: API, topic: number | Forum.Topic, text: string): Promise<Forum.Post>
- Make and send a Forum.Post in a Forum.Topic!
  Parameters
  - this: API
  - topic: number | Forum.Topic
    The topic or the id of the topic you're making your reply in
  - text: string
    Your reply! Your message!
  Returns Promise<Forum.Post>
  The reply you've made, as a Forum.Post!
  
  Scope
  "forum.write"
  
  Remarks
  Replying when the last post was made by the authorized user will likely cause the server to return a 403

Remarks

Replying when the last post was made by the authorized user will likely cause the server to return a 403

Returns

The reply you've made, as a Forum.Post!

Home Methods

`Readonly`searchUser

searchUser: (
    this: API,
    query: string,
    page?: number,
) => Promise<{ data: User[]; total: number }> = Home.Search.getUsers

Look for a user like you would on the website!

Type declaration

- (
      this: API,
      query: string,
      page?: number,
  ): Promise<{ data: User[]; total: number }>
- Look for a user like you would on the website!
  Parameters
  - this: API
  - query: string
    What you would put in the searchbar
  - page: number = 1
    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)
  Returns Promise<{ data: User[]; total: number }>

`Readonly`searchWiki

searchWiki: (
    this: API,
    query: string,
    page?: number,
) => Promise<{ data: WikiPage[]; total: number }> = Home.Search.getWikiPages

Look for a wiki page like you would on the website!

Type declaration

- (
      this: API,
      query: string,
      page?: number,
  ): Promise<{ data: WikiPage[]; total: number }>
- Look for a wiki page like you would on the website!
  Parameters
  - this: API
  - query: string
    What you would put in the searchbar
  - page: number = 1
    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)
  Returns Promise<{ data: WikiPage[]; total: number }>

Match Methods

`Readonly`getMatch

getMatch: (
    this: API,
    match: number | Info,
    query?: {
        after?: number | Match.Event;
        before?: number | Match.Event;
        limit?: number;
    },
) => Promise<Match> = Match.getOne

Get data of a multiplayer lobby from the stable (non-lazer) client that have URLs with community/matches or mp

Type declaration

- (
      this: API,
      match: number | Info,
      query?: {
          after?: number | Match.Event;
          before?: number | Match.Event;
          limit?: number;
      },
  ): Promise<Match>
- Get data of a multiplayer lobby from the stable (non-lazer) client that have URLs with community/matches or mp
  Parameters
  - this: API
  - match: number | Info
    The id of a match can be found at the end of its URL
  - Optionalquery: { after?: number | Match.Event; before?: number | Match.Event; limit?: number }
    Filter and limit the amount of events shown
    - Optionalafter?: number | Match.Event
      Filter FOR events AFTER this one
    - Optionalbefore?: number | Match.Event
      Filter FOR events BEFORE this one
    - Optionallimit?: number
      From 1 to 101 events (defaults to 100)
      
      Remarks
      0 is treated as 1, anything above 101 is treated as 101
  Returns Promise<Match>

`Readonly`getMatches

getMatches: (
    this: API,
    config?: Pick<Miscellaneous.Config, "sort" | "limit"> & {
        first_match_in_array?: number | Info;
    },
) => Promise<Info[]> = Match.getMultiple

Get the info about several matches!

Type declaration

- (
      this: API,
      config?: Pick<Miscellaneous.Config, "sort" | "limit"> & {
          first_match_in_array?: number | Info;
      },
  ): Promise<Info[]>
- Get the info about several matches!
  Parameters
  - this: API
  - Optionalconfig: Pick<Miscellaneous.Config, "sort" | "limit"> & {
    first_match_in_array?: number | Info;
    }
    The id of the first match of the array, and the sorting and size of said array
    - Optionalfirst_match_in_array?: number | Info
      Which match should be featured at index 0 of the returned array? Will get one with a similar id if it is unavailable
      
      Remarks
      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!
  Returns Promise<Info[]>

Miscellaneous Methods

`Readonly`getCountryRanking

getCountryRanking: (
    this: API,
    ruleset: Ruleset,
    page?: number,
) => Promise<Miscellaneous.Country.Ranking> = Miscellaneous.Country.getRanking

Get the top countries of a specific ruleset!

Type declaration

- (
      this: API,
      ruleset: Ruleset,
      page?: number,
  ): Promise<Miscellaneous.Country.Ranking>
- Get the top countries of a specific ruleset!
  Parameters
  - this: API
  - ruleset: Ruleset
    On which Ruleset should the countries be compared?
  - page: number = 1
    Imagine the array you get as a page, it can only have a maximum of 50 countries, while 50 others may be on the next one (defaults to 1)
  Returns Promise<Miscellaneous.Country.Ranking>

`Readonly`getSeasonalBackgrounds

getSeasonalBackgrounds: (
this: API,
) => Promise<{ backgrounds: { url: string; user: User }[]; ends_at: Date }> = Miscellaneous.getSeasonalBackgrounds

Get the backgrounds made and selected for this season or for last season!

Type declaration

- (
  this: API,
  ): Promise<{ backgrounds: { url: string; user: User }[]; ends_at: Date }>
- Get the backgrounds made and selected for this season or for last season!
  Parameters
  - this: API
  Returns Promise<{ backgrounds: { url: string; user: User }[]; ends_at: Date }>
  When the season ended, and for each background, its URL and its artist

Returns

When the season ended, and for each background, its URL and its artist

Multiplayer Methods

`Readonly`getPlaylistItemScores

getPlaylistItemScores: (
    this: API,
    item: Multiplayer.Room.PlaylistItem | { id: number; room_id: number },
    config?: Pick<Miscellaneous.Config, "sort" | "cursor_string" | "limit">,
) => Promise<
    {
        cursor_string: null
        | string;
        params: Pick<Miscellaneous.Config, "limit" | "sort">;
        scores: ScoreWithUser[];
        total: number;
        user_score: null | ScoreWithUser;
    },
> = Multiplayer.Room.PlaylistItem.getScores

Get the scores on a specific item of a room!

Type declaration

- (
      this: API,
      item: Multiplayer.Room.PlaylistItem | { id: number; room_id: number },
      config?: Pick<Miscellaneous.Config, "sort" | "cursor_string" | "limit">,
  ): Promise<
      {
          cursor_string: null
          | string;
          params: Pick<Miscellaneous.Config, "limit" | "sort">;
          scores: ScoreWithUser[];
          total: number;
          user_score: null | ScoreWithUser;
      },
  >
- Get the scores on a specific item of a room!
  Parameters
  - this: API
  - item: Multiplayer.Room.PlaylistItem | { id: number; room_id: number }
    An object with the id of the item in question, as well as the id of the room
  - Optionalconfig: Pick<Miscellaneous.Config, "sort" | "cursor_string" | "limit">
    How many scores, how are they sorted, is there a cursor_string?
  Returns Promise<
      {
          cursor_string: null
          | string;
          params: Pick<Miscellaneous.Config, "limit" | "sort">;
          scores: ScoreWithUser[];
          total: number;
          user_score: null | ScoreWithUser;
      },
  >
  Remarks
  This will not work for rooms created before ~March 5th 2024 https://github.com/ppy/osu-web/issues/10725

Remarks

This will not work for rooms created before ~March 5th 2024 https://github.com/ppy/osu-web/issues/10725

`Readonly`getRoom

getRoom: (
this: API,
room: number | Multiplayer.Room,
) => Promise<WithHostRecentparticipants> = Multiplayer.Room.getOne

Get data about a lazer multiplayer room (realtime or playlists)!

Type declaration

- (
  this: API,
  room: number | Multiplayer.Room,
  ): Promise<WithHostRecentparticipants>
- Get data about a lazer multiplayer room (realtime or playlists)!
  Parameters
  - this: API
  - room: number | Multiplayer.Room
    The room or the id of the room, can be found at the end of its URL (after /multiplayer/rooms/)
  Returns Promise<WithHostRecentparticipants>

`Readonly`getRoomEvents

getRoomEvents: (
    this: API,
    room: number | Multiplayer.Room,
) => Promise<
    {
        beatmaps: Beatmap[];
        beatmapsets: WithHype[];
        current_playlist_item_id: number;
        events: Multiplayer.Room.Event[];
        first_event_id: number;
        last_event_id: number;
        playlist_items: WithDetailsScores[];
        room: Multiplayer.Room;
        users: WithCountry[];
    },
> = Multiplayer.Room.Event.getAll

Get all the events about a lazer realtime room!

Type declaration

- (
      this: API,
      room: number | Multiplayer.Room,
  ): Promise<
      {
          beatmaps: Beatmap[];
          beatmapsets: WithHype[];
          current_playlist_item_id: number;
          events: Multiplayer.Room.Event[];
          first_event_id: number;
          last_event_id: number;
          playlist_items: WithDetailsScores[];
          room: Multiplayer.Room;
          users: WithCountry[];
      },
  >
- Get all the events about a lazer realtime room!
  Parameters
  - this: API
  - room: number | Multiplayer.Room
    The room (or its id) where the events occurred
  Returns Promise<
      {
          beatmaps: Beatmap[];
          beatmapsets: WithHype[];
          current_playlist_item_id: number;
          events: Multiplayer.Room.Event[];
          first_event_id: number;
          last_event_id: number;
          playlist_items: WithDetailsScores[];
          room: Multiplayer.Room;
          users: WithCountry[];
      },
  >
  Remarks
  It WILL error (422) if the provided room is not realtime, and may return empty arrays on rooms from roughly April 2025 or older

Remarks

It WILL error (422) if the provided room is not realtime, and may return empty arrays on rooms from roughly April 2025 or older

`Readonly`getRoomLeaderboard

getRoomLeaderboard: (
    this: API,
    room: number | Multiplayer.Room,
) => Promise<
    {
        leaderboard: Multiplayer.Room.Leader[];
        user_score: null
        | WithPosition;
    },
> = Multiplayer.Room.Leader.getMultiple

Get the room stats of all the users of that room!

Type declaration

- (
      this: API,
      room: number | Multiplayer.Room,
  ): Promise<
      {
          leaderboard: Multiplayer.Room.Leader[];
          user_score: null
          | WithPosition;
      },
  >
- Get the room stats of all the users of that room!
  Parameters
  - this: API
  - room: number | Multiplayer.Room
    The room or the id of the room in question
  Returns Promise<
      {
          leaderboard: Multiplayer.Room.Leader[];
          user_score: null
          | WithPosition;
      },
  >
  An object with the leaderboard, and the score and position of the authorized user under user_score

Returns

An object with the leaderboard, and the score and position of the authorized user under user_score

`Readonly`getRooms

Get playlists/realtime rooms that are active, that have ended, that the user participated in, that the user made, or just simply any room!

Type declaration

- (
      this: API,
      type: "playlists" | "realtime",
      mode: "all" | "active" | "ended" | "participated" | "owned",
      limit?: number,
      sort?: "ended" | "created",
      season_id?: number,
  ): Promise<WithHostRecentparticipants[]>
- Get playlists/realtime rooms that are active, that have ended, that the user participated in, that the user made, or just simply any room!
  Parameters
  - this: API
  - type: "playlists" | "realtime"
    Whether the multiplayer rooms are in playlist format (like current spotlights) or realtime
  - mode: "all" | "active" | "ended" | "participated" | "owned"
    The state of the room, or the relation of the authorized user with the room
  - limit: number = 10
    The maximum amount of rooms to return, defaults to 10
  - sort: "ended" | "created" = "created"
    Sort (where most recent is first) by creation date or end date, defaults to the creation date
  - Optionalseason_id: number
    Only 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!!)
  Returns Promise<WithHostRecentparticipants[]>
  Scope
  "public"

NewsPost Methods

`Readonly`getNewsPost

getNewsPost: (
this: API,
post: string | number | NewsPost,
) => Promise<WithContentNavigation> = NewsPost.getOne

Get a NewsPost, its content, and the NewsPosts right before and right after it!

Type declaration

- (this: API, post: string | number | NewsPost): Promise<WithContentNavigation>
- Get a NewsPost, its content, and the NewsPosts right before and right after it!
  Parameters
  - this: API
  - post: string | number | NewsPost
    The NewsPost, or its id, or its slug
  Returns Promise<WithContentNavigation>

`Readonly`getNewsPosts

getNewsPosts: (this: API, year?: number) => Promise<NewsPost[]> = NewsPost.getMultiple

Get all the NewsPosts of a specific year!

Type declaration

- (this: API, year?: number): Promise<NewsPost[]>
- Get all the NewsPosts of a specific year!
  Parameters
  - this: API
  - Optionalyear: number
    The year the posts were made (defaults to current year)
  Returns Promise<NewsPost[]>
  Remarks
  If the specified year is invalid/has no news, it fallbacks to the default year

Remarks

If the specified year is invalid/has no news, it fallbacks to the default year

Score Methods

`Readonly`getReplay

getReplay: (this: API, score: number | Score) => Promise<string> = Score.getReplay

Get the replay for a score!

Type declaration

- (this: API, score: number | Score): Promise<string>
- Get the replay for a score!
  Parameters
  - this: API
  - score: number | Score
    The score that has created the replay
  Returns Promise<string>
  The correctly encoded content of what would be a replay file (you can just fs.writeFileSync with it!)
  
  Scope
  "public"

Returns

The correctly encoded content of what would be a replay file (you can just fs.writeFileSync with it!)

`Readonly`getScores

getScores: (
    this: API,
    config?: Pick<Miscellaneous.Config, "cursor_string"> & {
        ruleset?: "osu" | "taiko" | "fruits" | "mania";
    },
) => Promise<{ cursor_string: string; scores: Score[] }> = Score.getSome

Get up to the 1000 (!!) most recent scores!

Type declaration

- (
      this: API,
      config?: Pick<Miscellaneous.Config, "cursor_string"> & {
          ruleset?: "osu" | "taiko" | "fruits" | "mania";
      },
  ): Promise<{ cursor_string: string; scores: Score[] }>
- Get up to the 1000 (!!) most recent scores!
  Parameters
  - this: API
  - Optionalconfig: Pick<Miscellaneous.Config, "cursor_string"> & {
    ruleset?: "osu" | "taiko" | "fruits" | "mania";
    }
    Specify the ruleset as a filter, or use a cursor_string to get even more scores
  Returns Promise<{ cursor_string: string; scores: Score[] }>
  Remarks
  You may get any amount of scores, from 0 to 1000, 0 being more likely when using a cursor_string

Remarks

You may get any amount of scores, from 0 to 1000, 0 being more likely when using a cursor_string

Spotlight Methods

`Readonly`getSpotlightRanking

getSpotlightRanking: (
    this: API,
    ruleset: Ruleset,
    spotlight: number | Spotlight,
    filter?: "all" | "friends",
) => Promise<Spotlight.Ranking> = Spotlight.getRanking

Get the rankings of a spotlight from 2009 to 2020 on a specific ruleset!

Type declaration

- (
      this: API,
      ruleset: Ruleset,
      spotlight: number | Spotlight,
      filter?: "all" | "friends",
  ): Promise<Spotlight.Ranking>
- Get the rankings of a spotlight from 2009 to 2020 on a specific ruleset!
  Parameters
  - this: API
  - ruleset: Ruleset
    Each spotlight has a different ranking (and often maps) depending on the ruleset
  - spotlight: number | Spotlight
    The spotlight in question
  - filter: "all" | "friends" = "all"
    What kind of players do you want to see? Keep in mind friends has no effect if no authorized user (defaults to all)
  Returns Promise<Spotlight.Ranking>

`Readonly`getSpotlights

getSpotlights: (this: API) => Promise<Spotlight[]> = Spotlight.getAll

Get ALL legacy spotlights! (2009-2020, somewhat known as charts/ranking charts, available @ https://osu.ppy.sh/rankings/osu/charts)

Type declaration

- (this: API): Promise<Spotlight[]>
- Get ALL legacy spotlights! (2009-2020, somewhat known as charts/ranking charts, available @ https://osu.ppy.sh/rankings/osu/charts)
  Parameters
  - this: API
  Returns Promise<Spotlight[]>
  Remarks
  The data for newer spotlights (2020 onwards, 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 :(

Remarks

The data for newer spotlights (2020 onwards, 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 :(

User Methods

`Readonly`getFriends

getFriends: (this: API) => Promise<Relation[]> = User.getFriends

Get user data of each friend of the authorized user

Type declaration

- (this: API): Promise<Relation[]>
- Get user data of each friend of the authorized user
  Parameters
  - this: API
  Returns Promise<Relation[]>
  Scope
  "friends.read"
  
  Remarks
  The Statistics will be of the authorized user's favourite ruleset, not the friend's!

Remarks

The Statistics will be of the authorized user's favourite ruleset, not the friend's!

`Readonly`getKudosuRanking

getKudosuRanking: (this: API) => Promise<WithKudosu[]> = User.Kudosu.getRanking

Get the top 50 players who have the most total kudosu!

Type declaration

- (this: API): Promise<WithKudosu[]>
- Get the top 50 players who have the most total kudosu!
  Parameters
  - this: API
  Returns Promise<WithKudosu[]>

`Readonly`getResourceOwner

getResourceOwner: (
this: API,
ruleset?: Ruleset,
) => Promise<WithStatisticsrulesets> = User.getResourceOwner

Get extensive user data about the authorized user

Type declaration

- (this: API, ruleset?: Ruleset): Promise<WithStatisticsrulesets>
- Get extensive user data about the authorized user
  Parameters
  - this: API
  - Optionalruleset: Ruleset
    The data should be relevant to which ruleset? (defaults to user's default Ruleset)
  Returns Promise<WithStatisticsrulesets>
  Scope
  "identify"

`Readonly`getUser

getUser: (
    this: API,
    user: string | number | User,
    ruleset?: Ruleset,
) => Promise<User.Extended> = User.getOne

Get extensive user data about whoever you want!

Type declaration

- (
      this: API,
      user: string | number | User,
      ruleset?: Ruleset,
  ): Promise<User.Extended>
- Get extensive user data about whoever you want!
  Parameters
  - this: API
  - user: string | number | User
    A user id, a username or a User object!
  - Optionalruleset: Ruleset
    The data should be relevant to which ruleset? (defaults to user's default Ruleset)
  Returns Promise<User.Extended>

`Readonly`getUserBeatmaps

Get beatmaps favourited or made by a user!

Type declaration

- (
      this: API,
      user: number | User,
      type:
          | "loved"
          | "graveyard"
          | "pending"
          | "ranked"
          | "favourite"
          | "guest"
          | "nominated",
      config?: User.Config,
  ): Promise<Beatmapset.Extended.WithBeatmap[]>
- Get beatmaps favourited or made by a user!
  Parameters
  - this: API
  - user: number | User
    The user in question
  - type:
        | "loved"
        | "graveyard"
        | "pending"
        | "ranked"
        | "favourite"
        | "guest"
        | "nominated"
    The relation between the user and the beatmaps
  - Optionalconfig: User.Config
    Array limit & offset
  Returns Promise<Beatmapset.Extended.WithBeatmap[]>

`Readonly`getUserKudosuHistory

getUserKudosuHistory: (
    this: API,
    user: number | User,
    config?: User.Config,
) => Promise<History[]> = User.Kudosu.getHistory

Get data about the history of a user's kudosu!

Type declaration

- (this: API, user: number | User, config?: User.Config): Promise<History[]>
- Get data about the history of a user's kudosu!
  Parameters
  - this: API
  - user: number | User
    The user in question
  - Optionalconfig: User.Config
    Array limit & offset
  Returns Promise<History[]>

`Readonly`getUserMostPlayed

getUserMostPlayed: (
    this: API,
    user: number | User,
    config?: User.Config,
) => Promise<Playcount[]> = User.getMostPlayed

Get the beatmaps most played by a user!

Type declaration

- (this: API, user: number | User, config?: User.Config): Promise<Playcount[]>
- Get the beatmaps most played by a user!
  Parameters
  - this: API
  - user: number | User
    The user who played the beatmaps
  - Optionalconfig: User.Config
    Array limit & offset
  Returns Promise<Playcount[]>

`Readonly`getUserRanking

getUserRanking: (
    this: API,
    ruleset: Ruleset,
    type: "score" | "performance",
    config?: {
        country?: string;
        filter?: "all" | "friends";
        page?: number;
        variant?: "4k" | "7k";
    },
) => Promise<User.Ranking> = User.getRanking

Get the top players of the game, with some filters!

Type declaration

- (
      this: API,
      ruleset: Ruleset,
      type: "score" | "performance",
      config?: {
          country?: string;
          filter?: "all" | "friends";
          page?: number;
          variant?: "4k" | "7k";
      },
  ): Promise<User.Ranking>
- Get the top players of the game, with some filters!
  Parameters
  - this: API
  - ruleset: Ruleset
    Self-explanatory, is also known as "Gamemode"
  - type: "score" | "performance"
    Rank players by their performance points or by their ranked score?
  - Optionalconfig: {
        country?: string;
        filter?: "all" | "friends";
        page?: number;
        variant?: "4k" | "7k";
    }
    Specify which page, country, filter out non-friends...
    - Optionalcountry?: string
      Only get players from a specific country, using its ISO 3166-1 alpha-2 country code! (France would be FR, United States US)
    - Optionalfilter?: "all" | "friends"
      What kind of players do you want to see? Keep in mind friends has no effect if no authorized user
    - Optionalpage?: number
      Imagine 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
    - Optionalvariant?: "4k" | "7k"
      If type is performance and ruleset is mania, choose between 4k and 7k!
  Returns Promise<User.Ranking>

`Readonly`getUserRecentActivity

getUserRecentActivity: (
    this: API,
    user: number | User,
    config?: User.Config,
) => Promise<AnyRecentActivity[]> = User.getRecentActivity

Get 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)

Type declaration

- (
      this: API,
      user: number | User,
      config?: User.Config,
  ): Promise<AnyRecentActivity[]>
- Get 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)
  Parameters
  - this: API
  - user: number | User
    The user in question
  - Optionalconfig: User.Config
    Array limit & offset
  Returns Promise<AnyRecentActivity[]>

`Readonly`getUsers

getUsers: (
    this: API,
    users: (number | User)[],
    include_variant_statistics?: boolean,
) => Promise<WithCountryCoverGroupsTeamStatisticsrulesets[]> = User.getMultiple

Get user data for up to 50 users at once!

Type declaration

- (
      this: API,
      users: (number | User)[],
      include_variant_statistics?: boolean,
  ): Promise<WithCountryCoverGroupsTeamStatisticsrulesets[]>
- Get user data for up to 50 users at once!
  Parameters
  - this: API
  - users: (number | User)[]
    An array containing user ids or/and User objects!
  - include_variant_statistics: boolean = false
    Should the response include variants, useful to get stats specific to mania 4k/7k for example? (defaults to false)
  Returns Promise<WithCountryCoverGroupsTeamStatisticsrulesets[]>

`Readonly`getUserScores

getUserScores: (
    this: API,
    user: number | User,
    type: "best" | "firsts" | "recent",
    ruleset?: Ruleset,
    include?: { fails?: boolean; lazer?: boolean },
    config?: User.Config,
) => Promise<WithUserBeatmapBeatmapset[]> = User.getScores

Get "notable" scores from a user

Type declaration

- (
      this: API,
      user: number | User,
      type: "best" | "firsts" | "recent",
      ruleset?: Ruleset,
      include?: { fails?: boolean; lazer?: boolean },
      config?: User.Config,
  ): Promise<WithUserBeatmapBeatmapset[]>
- Get "notable" scores from a user
  Parameters
  - this: API
  - user: number | User
    The user who set the scores
  - type: "best" | "firsts" | "recent"
    Do you want scores: in the user's top 100, that are top 1 on a beatmap, that have been recently set?
  - Optionalruleset: Ruleset
    The Ruleset the scores were made in (defaults to user's default Ruleset)
  - include: { fails?: boolean; lazer?: boolean } = ...
    Do you also want lazer scores and failed scores? (defaults to true for lazer & false for fails)
  - Optionalconfig: User.Config
    Array limit & offset
  Returns Promise<WithUserBeatmapBeatmapset[]>

`Readonly`lookupUsers

lookupUsers: (
this: API,
users: (number | User)[],
) => Promise<WithCountryCoverGroupsTeam[]> = User.lookupMultiple

Lookup user data for up to 50 users at once!

Type declaration

- (this: API, users: (number | User)[]): Promise<WithCountryCoverGroupsTeam[]>
- Lookup user data for up to 50 users at once!
  Parameters
  - this: API
  - users: (number | User)[]
    An array containing user ids or/and User objects!
  Returns Promise<WithCountryCoverGroupsTeam[]>

WikiPage Methods

`Readonly`getWikiPage

getWikiPage: (this: API, path: string, locale?: string) => Promise<WikiPage> = WikiPage.getOne

Get a wiki page!

Type declaration

- (this: API, path: string, locale?: string): Promise<WikiPage>
- Get a wiki page!
  Parameters
  - this: API
  - path: string
    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!)
  - locale: string = "en"
    Lowercase language tag ("fr" for french, "pt-br" for brazilian portuguese) (defaults to en)
  Returns Promise<WikiPage>

Class API

Hierarchy (View Summary)

Index

Constructors

Accessors

Methods

Beatmap Methods

Beatmapset Methods

Changelog Methods

Chat Methods

Comment Methods

Event Methods

Forum Methods

Home Methods

Match Methods

Miscellaneous Methods

Multiplayer Methods

NewsPost Methods

Score Methods

Spotlight Methods

User Methods

WikiPage Methods

Constructors

constructor

Parameters

Returns API

Accessors

access_token

Returns string

Parameters

Returns void

client_id

Returns number

Parameters

Returns void

client_secret

Returns string

Parameters

Returns void

expires

Returns Date

Parameters

Returns void

headers

Returns { [key: string]: any }

Parameters

Returns void

refresh_token

Returns undefined | string

Parameters

Returns void

refresh_token_on_401

Returns boolean

Parameters

Returns void

refresh_token_on_expires

Returns boolean

Parameters

Returns void

refresh_token_timer

Returns undefined | Timeout

Parameters

Returns void

retry_delay

Returns number

Parameters

Returns void

retry_maximum_amount

Returns number

Remarks

Parameters

Returns void

retry_on_automatic_token_refresh

Returns boolean

Parameters

Returns void

retry_on_status_codes

Returns number[]

Parameters

Returns void

`Static`createAsync

`Readonly`getBeatmap

`Readonly`getBeatmapDifficultyAttributes

`Readonly`getBeatmapDifficultyAttributesFruits