MENU

Introduction

Welcome to the documentation for osu!api v2. You can use this API to get information on various circles and those who click them.

Note that while we endeavour to keep this documentation up to date, consider it a work-in-progress and note that it will likely contain errors.

If you notice any errors in the documentation or encounter problems using the API, please check for (or create if necessary) issues on GitHub. Alternatively, you can ask in #osu-web on the development discord.

Code examples are provided in the dark area to the right, you can use the tabs at the top of the page to switch between bash and javascript samples.

Terms of Use

Use the API for good. Don't overdo it. If in doubt, ask before (ab)using :). this section may expand as necessary.

Current rate limit is set at an insanely high 1200 requests per minute, with burst capability of up to 200 beyond that. If you require more, you probably fall into the above category of abuse. If you are doing more than 60 requests a minute, you should probably give peppy a yell.

Wrappers

Below is a list of some language-specific wrappers maintained by the community. Your mileage may vary when using them – please report any issues to the wrapper first before reporting back to us.

Changelog

For a full list of changes, see the Changelog on the site.

Breaking Changes

2024-07-30

2024-01-23

2023-10-17

2023-09-11

2023-02-17

2023-01-05

2022-11-21

2022-11-11

2022-09-27

2022-07-06

2022-06-08

2021-10-28

2021-09-01

2021-08-11

2021-06-14

2021-06-09

2021-04-20

2021-02-25

2020-09-08

2020-08-28

2020-05-01

2020-02-18

2019-10-09

2019-07-18

Endpoint

Base URL

The base URL is: https://osu.ppy.sh/api/[version]/

API Versions

This is combined with the base endpoint to determine where requests should be sent.

Version Status
v2 current
v1 legacy api provided by the old site, will be deprecated soon

API Response Version

Sometimes, an API response need to be updated in non-backward compatible ways. In such cases, the x-api-version header is used to determine which version of the response will be returned.

Version 0 is assumed when the header is omitted.

Version Change
20220705 Score object with different set of fields.
20240529 GET /rooms will not return rooms with category daily_challenge prior to this version. Temporary, will not be supported after 2024-11-29.

Language

Language for the response is determined by Accept-Language header when specified. Specifying * or not setting the header will set the language to user configured language when accessing API as a user.

Authentication

Routes marked with the OAuth label require a valid OAuth2 token for access.

More information about applications you have registered and granted permissions to can be found here.

The API supports the following grant types:

Before you can use the osu!api, you will need to

  1. have registered an OAuth Application.
  2. acquire an access token by either:
    • authorizing users for your application;
    • requesting Client Credentials token.

Registering an OAuth application

Before you can get an OAuth token, you will need to register an OAuth application on your account settings page.

To register an OAuth application you will need to provide the:

Name Description
Application Name This is the name that will be visible to users of your application. The name of your application cannot be changed.
Application Callback URL The URL in your application where users will be sent after authorization.

The Application Callback URL is required when for using Authorization Codes. This may be left blank if you are only using Client Credentials Grants.

Your new OAuth application will have a Client ID and Client Secret; the Client Secret is like a password for your OAuth application, it should be kept private and do not share it with anyone else.

Authorization Code Grant

The flow to authorize users for your application is:

  1. Requesting authorization from users
  2. Users are redirected back to your site
  3. Your application accesses the API with the user's access token

Request authorization from a user

To obtain an access token, you must first get an authorization code that is created when a user grants permissions to your application. To request permission from the user, they should be redirected to:

Example request:
curl --request GET \
    --get "https://osu.ppy.sh/oauth/authorize?client_id=1&redirect_uri=http%3A%2F%2Flocalhost%3A4000&response_type=code&scope=public+identify&state=randomval"
const url = new URL(
    "https://osu.ppy.sh/oauth/authorize"
);

const params = {
    "client_id": "1",
    "redirect_uri": "http://localhost:4000",
    "response_type": "code",
    "scope": "public identify",
    "state": "randomval",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

fetch(url, {
    method: "GET",
}).then(response => response.json());

GET https://osu.ppy.sh/oauth/authorize

Query Parameters

client_id   integer   

The Client ID you received when you registered.

redirect_uri   string  optional  

The URL in your application where users will be sent after authorization. This must match the registered Application Callback URL exactly.

response_type   string   

This should always be code when requesting authorization.

scope   string  optional  

A space-delimited string of scopes.

state   string  optional  

Data that will be returned when a temporary code is issued. It can be used to provide a token for protecting against cross-site request forgery attacks.

User is redirected back to your site

If the user accepts your request, they will be redirected back to your site with a temporary single-use code contained in the URL parameter. If a state value was provided in the previous request, it will be returned here.

Exchange this code for an access token:

Example request:
curl --request POST \
    "https://osu.ppy.sh/oauth/token" \
    --header "Accept: application/json" \
    --header "Content-Type: application/x-www-form-urlencoded" \
    --data "client_id=1&client_secret=clientsecret&code=receivedcode&grant_type=authorization_code&redirect_uri=http%3A%2F%2Flocalhost%3A4000"

const url = new URL(
    "https://osu.ppy.sh/oauth/token"
);

const headers = {
    "Accept": "application/json",
    "Content-Type": "application/x-www-form-urlencoded",
};

let body = "client_id=1&client_secret=clientsecret&code=receivedcode&grant_type=authorization_code&redirect_uri=http%3A%2F%2Flocalhost%3A4000";

fetch(url, {
    method: "POST",
    headers,
    body: body,
}).then(response => response.json());

Example response (200):

{
    "access_token": "verylongstring",
    "expires_in": 86400,
    "refresh_token": "anotherlongstring",
    "token_type": "Bearer"
}

POST https://osu.ppy.sh/oauth/token

Headers

Accept      

Example: application/json

Content-Type      

Example: application/x-www-form-urlencoded

Body Parameters

client_id   string   

The client ID of your application.

client_secret   string   

The client secret of your application.

code   string   

The code you received.

grant_type   string   

This must always be authorization_code

redirect_uri   string  optional  

This must be the same as the one used on authorization request.

Response Format

Successful requests will be issued an access token:

Name Type Description
token_type string The type of token, this should always be Bearer.
expires_in integer The number of seconds the token will be valid for.
access_token string The access token.
refresh_token string The refresh token.

Refresh access token

Access token expires after some time as per expires_in field. Refresh the token to get new access token without going through authorization process again.

Use refresh_token received during previous access token request:

Example request:
curl --request POST \
    "https://osu.ppy.sh/oauth/token" \
    --header "Accept: application/json" \
    --header "Content-Type: application/x-www-form-urlencoded" \
    --data "client_id=1&client_secret=clientsecret&grant_type=refresh_token&refresh_token=longstring&scope=public+identify"

const url = new URL(
    "https://osu.ppy.sh/oauth/token"
);

const headers = {
    "Accept": "application/json",
    "Content-Type": "application/x-www-form-urlencoded",
};

let body = "client_id=1&client_secret=clientsecret&grant_type=refresh_token&refresh_token=longstring&scope=public+identify";

fetch(url, {
    method: "POST",
    headers,
    body: body,
}).then(response => response.json());

Example response (200):

{
    "access_token": "verylongstring",
    "expires_in": 86400,
    "refresh_token": "anotherlongstring",
    "token_type": "Bearer"
}

POST https://osu.ppy.sh/oauth/token

Headers

Accept      

Example: application/json

Content-Type      

Example: application/x-www-form-urlencoded

Body Parameters

client_id   integer   

The Client ID you received when you registered.

client_secret   string   

The client secret of your application.

grant_type   string   

This must always be refresh_token.

refresh_token   string   

Value of refresh token received from previous access token request.

scope   string  optional  

A space-delimited string of scopes. Specifying fewer scopes than existing access token is allowed but subsequent refresh tokens can't re-add removed scopes. If this isn't specified, existing access token scopes will be used.

Response Format

Successful requests will be issued an access token and a new refresh token:

Name Type Description
token_type string The type of token, this should always be Bearer.
expires_in integer The number of seconds the token will be valid for.
access_token string The access token.
refresh_token string The refresh token.

Client Credentials Grant

The client credential flow provides a way for developers to get access tokens that do not have associated user permissions; as such, these tokens are considered as guest users.

Example for requesting Client Credentials token:

Example request:
curl --request POST \
    "https://osu.ppy.sh/oauth/token" \
    --header "Accept: application/json" \
    --header "Content-Type: application/x-www-form-urlencoded" \
    --data "client_id=1&client_secret=clientsecret&grant_type=client_credentials&scope=public"

const url = new URL(
    "https://osu.ppy.sh/oauth/token"
);

const headers = {
    "Accept": "application/json",
    "Content-Type": "application/x-www-form-urlencoded",
};

let body = "client_id=1&client_secret=clientsecret&grant_type=client_credentials&scope=public";

fetch(url, {
    method: "POST",
    headers,
    body: body,
}).then(response => response.json());

Example response (200):

{
    "access_token": "verylongstring",
    "expires_in": 86400,
    "token_type": "Bearer"
}

POST https://osu.ppy.sh/oauth/token

Headers

Accept      

Example: application/json

Content-Type      

Example: application/x-www-form-urlencoded

Body Parameters

client_id   integer   

The Client ID you received when you registered.

client_secret   string   

The client secret of your application.

grant_type   string   

This must always be client_credentials.

scope   string   

Must be public; other scopes have no meaningful effect.

Response Format

Successful requests will be issued an access token:

Name Type Description
token_type string The type of token, this should always be Bearer.
expires_in integer The number of seconds the token will be valid for.
access_token string The access token.

Using the access token to access the API

With the access token, you can make requests to osu!api on behalf of a user.

The token should be included in the header of requests to the API.

Authorization: Bearer {{token}} 

# With shell, you can just pass the correct header with each request
curl "https://osu.ppy.sh/api/[version]/[endpoint]"
  -H "Authorization: Bearer {{token}}"




    
// This javascript example uses fetch()
fetch("https://osu.ppy.sh/api/[version]/[endpoint]", {
    headers: {
      Authorization: 'Bearer {{token}}'
    }
});





Make sure to replace {{token}} with your OAuth2 token.






Resource Owner




    The Resource Owner is the user that a token acts on behalf of.





    For Authorization Code Grant tokens, the Resource Owner is the user authorizing the token.





    Client Credentials Grant tokens do not have a Resource Owner (i.e. is a guest user), unless they have been granted the delegate scope. The Resource Owner of tokens with the delegate scope is the owner of the OAuth Application that was granted the token.





    Routes marked with requires user require the use of tokens that have a Resource Owner.





Client Credentials Delegation




    Client Credentials Grant tokens may be allowed to act on behalf of the owner of the OAuth client (delegation) by requesting the delegate scope, in addition to other scopes supporting delegation.
    When using delegation, scopes that support delegation cannot be used together with scopes that do not support delegation.
    Delegation is only available to Chat Bots.





    The following scopes currently support delegation:





    
        

            Name
        

    
    
        

            chat.write
        

    




Scopes




    The following scopes are currently supported:






    
        

            Name
            Description
        

    
    
                    

                
                    chat.read
                
                
Allows read chat messages on a user's behalf.


            

                    

                
                    chat.write
                
                
Allows sending chat messages on a user's behalf.


            

                    

                
                    chat.write_manage
                
                
Allows joining and leaving chat channels on a user's behalf.


            

                    

                
                    delegate
                
                
Allows acting as the owner of a client; only available for Client Credentials Grant.


            

                    

                
                    forum.write
                
                
Allows creating and editing forum posts on a user's behalf.


            

                    

                
                    friends.read
                
                
Allows reading of the user's friend list.


            

                    

                
                    identify
                
                
Allows reading of the public profile of the user (/me).


            

                    

                
                    public
                
                
Allows reading of publicly available data on behalf of the user.


            

                

        

    





    identify is the default scope for the Authorization Code Grant and always implicitly provided. The Client Credentials Grant does not currently have any default scopes.





    Routes marked with lazer are intended for use by the osu!lazer client and not currently available for use with Authorization Code or Client Credentials grants.





    Using the chat.write scope requires either
    






Managing OAuth applications




    Your account settings page will show your registered OAuth applications, and all the OAuth applications you have granted permissions to.




Reset Client Secret




    You can generate a new Client Secret by choosing to "Reset client secret", however, this will disable all access tokens issued for the application.


        
Beatmap Packs


    

                                
Get Beatmap Packs




    
            OAuth
            public
    



Returns a list of beatmap packs.




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/beatmaps/packs?type=ipsum" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/beatmaps/packs"
);

const params = {
    "type": "ipsum",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





    



Request

    

        GET
        /beatmaps/packs
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
Query Parameters

                    

            type  
string 
optional  
                
    


BeatmapPackType of the beatmap packs to be returned. Defaults to standard.

        

                    

            cursor_string  
string 
optional  
                
    


CursorString for pagination.

        

    




Response format






Field
Type






beatmap_packs
BeatmapPack[]





                    
Get Beatmap Pack




    
            OAuth
            public
    



Gets the beatmap pack for the specified beatmap pack tag.




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/beatmaps/packs/ab?legacy_only=0" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/beatmaps/packs/ab"
);

const params = {
    "legacy_only": "0",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





    



Request

    

        GET
        /beatmaps/packs/{pack}
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            pack  
string 
  
                
    


The tag of the beatmap pack to be returned.

        

        
Query Parameters

                    

            legacy_only  
integer 
optional  
                
    


Whether or not to consider lazer scores for user completion data. Defaults to 0.

        

    




Response format


Returns BeatmapPack object.
The following attributes are always included as well:






Attribute






beatmapsets




user_completion_data





                
Beatmaps


    

                                
Lookup Beatmap




    
            OAuth
            public
    



Returns beatmap.




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/beatmaps/lookup?checksum=dolores&filename=nam&id=ad" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/beatmaps/lookup"
);

const params = {
    "checksum": "dolores",
    "filename": "nam",
    "id": "ad",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





            

            
Example response (200):

        

                
"See Beatmap object section"
 

    



Request

    

        GET
        /beatmaps/lookup
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
Query Parameters

                    

            checksum  
string 
optional  
                
    


A beatmap checksum.

        

                    

            filename  
string 
optional  
                
    


A filename to lookup.

        

                    

            id  
string 
optional  
                
    


A beatmap ID to lookup.

        

    




Response format


See Get Beatmap

                    
Get a User Beatmap score




    
            OAuth
            public
    



Return a User's score on a Beatmap




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/beatmaps/1/scores/users/18?legacy_only=0&mode=alias&mods=veritatis" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/beatmaps/1/scores/users/18"
);

const params = {
    "legacy_only": "0",
    "mode": "alias",
    "mods": "veritatis",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





    



Request

    

        GET
        /beatmaps/{beatmap}/scores/users/{user}
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            beatmap  
integer 
  
                
    


Id of the Beatmap.

        

            

            user  
integer 
  
                
    


Id of the User.

        

        
Query Parameters

                    

            legacy_only  
integer 
optional  
                
    


Whether or not to exclude lazer scores. Defaults to 0.

        

                    

            mode  
string 
optional  
                
    


The Ruleset to get scores for.

        

                    

            mods  
string 
optional  
                
    


An array of matching Mods, or none // TODO.

        

    




Response Format


Returns BeatmapUserScore


The position returned depends on the requested mode and mods.

                    
Get a User Beatmap scores




    
            OAuth
            public
    



Return a User's scores on a Beatmap




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/beatmaps/15/scores/users/8/all?legacy_only=0&ruleset=osu" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/beatmaps/15/scores/users/8/all"
);

const params = {
    "legacy_only": "0",
    "ruleset": "osu",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





    



Request

    

        GET
        /beatmaps/{beatmap}/scores/users/{user}/all
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            beatmap  
integer 
  
                
    


Id of the Beatmap.

        

            

            user  
integer 
  
                
    


Id of the User.

        

        
Query Parameters

                    

            legacy_only  
integer 
optional  
                
    


Whether or not to exclude lazer scores. Defaults to 0.

        

                    

            mode  
string 
optional  
                
    


(deprecated) The Ruleset to get scores for. Defaults to beatmap ruleset.

        

                    

            ruleset  
string 
optional  
                
    


The Ruleset to get scores for. Defaults to beatmap ruleset.

        

    




Response Format






Field
Type






scores
Score[]





                    
Get Beatmap scores




    
            OAuth
            public
    



Returns the top scores for a beatmap. Depending on user preferences, this may only show legacy scores.




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/beatmaps/5/scores?legacy_only=0&mode=nostrum&mods=laborum&type=fugit" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/beatmaps/5/scores"
);

const params = {
    "legacy_only": "0",
    "mode": "nostrum",
    "mods": "laborum",
    "type": "fugit",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





    



Request

    

        GET
        /beatmaps/{beatmap}/scores
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            beatmap  
integer 
  
                
    


Id of the Beatmap.

        

        
Query Parameters

                    

            legacy_only  
integer 
optional  
                
    


Whether or not to exclude lazer scores. Defaults to 0.

        

                    

            mode  
string 
optional  
                
    


The Ruleset to get scores for.

        

                    

            mods  
string 
optional  
                
    


An array of matching Mods, or none // TODO.

        

                    

            type  
string 
optional  
                
    


Beatmap score ranking type // TODO.

        

    




Response Format


Returns BeatmapScores. Score object inside includes user and the included user includes country and cover.

                    
Get Beatmap scores (non-legacy)




    
            OAuth
            public
    



Returns the top scores for a beatmap.




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/beatmaps/12/solo-scores?mode=laboriosam&mods=quia&type=sapiente" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/beatmaps/12/solo-scores"
);

const params = {
    "mode": "laboriosam",
    "mods": "quia",
    "type": "sapiente",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





    



Request

    

        GET
        /beatmaps/{beatmap}/solo-scores
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            beatmap  
integer 
  
                
    


Id of the Beatmap.

        

        
Query Parameters

                    

            mode  
string 
optional  
                
    


The Ruleset to get scores for.

        

                    

            mods  
string 
optional  
                
    


An array of matching Mods, or none // TODO.

        

                    

            type  
string 
optional  
                
    


Beatmap score ranking type // TODO.

        

    




Response Format


Returns BeatmapScores. Score object inside includes user and the included user includes country and cover.

                    
Get Beatmaps




    
            OAuth
            public
    



Returns a list of beatmaps.




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/beatmaps?ids%5B%5D=1" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/beatmaps"
);

const params = {
    "ids[]": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





            

            
Example response (200):

        

                
{
  "beatmaps": [
    {
      "id": 1,
      // Other Beatmap attributes...
    }
  ]
}
 

    



Request

    

        GET
        /beatmaps
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
Query Parameters

                    

            ids[]  
integer 
optional  
                
    


Beatmap IDs to be returned. Specify once for each beatmap ID requested. Up to 50 beatmaps can be requested at once.

        

    




Response format






Field
Type
Description






beatmaps
BeatmapExtended[]
Includes beatmapset (with ratings), failtimes, and max_combo.





                    
Get Beatmap




    
            OAuth
            public
    



Gets beatmap data for the specified beatmap ID.




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/beatmaps/11" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/beatmaps/11"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





            

            
Example response (200):

        

                
"See Beatmap object section."
 

    



Request

    

        GET
        /beatmaps/{beatmap}
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            beatmap  
integer 
  
                
    


The ID of the beatmap.

        

    




Response format


Returns BeatmapExtended object.
Following attributes are included in the response object when applicable,






Attribute
Notes






beatmapset
Includes ratings property.




failtimes





max_combo






                    
Get Beatmap Attributes




    
            OAuth
            public
    



Returns difficulty attributes of beatmap with specific mode and mods combination.




Example request:





    
curl --request POST \
    "https://osu.ppy.sh/api/v2/beatmaps/2/attributes" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"mods\": 1,
    \"ruleset\": \"osu\"
}"






    
const url = new URL(
    "https://osu.ppy.sh/api/v2/beatmaps/2/attributes"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "mods": 1,
    "ruleset": "osu"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());





            

            
Example response (200):

        

                
{
  "attributes": {
      "max_combo": 100,
      ...
  }
}
 

    



Request

    

        POST
        /beatmaps/{beatmap}/attributes
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            beatmap  
integer 
  
                
    


Beatmap id.

        

        
Body Parameters

    

            mods  
integer|string[]|Mod[] 
optional  
                
        
    


Mod combination. Can be either a bitset of mods, array of mod acronyms, or array of mods. Defaults to no mods.

        

                

            ruleset  
Ruleset 
optional  
                
    


Ruleset of the difficulty attributes. Only valid if it's the beatmap ruleset or the beatmap can be converted to the specified ruleset. Defaults to ruleset of the specified beatmap.

        

                

            ruleset_id  
integer 
optional  
                
    


The same as ruleset but in integer form.

        

    




Response format






Field
Type






Attributes
DifficultyAttributes





                
Beatmapset Discussions


    

                                
Get Beatmapset Discussion Posts




    
            OAuth
            public
    



Returns the posts of beatmapset discussions.




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/beatmapsets/discussions/posts?beatmapset_discussion_id=similique&limit=17&page=2&sort=cupiditate&types%5B%5D=voluptatum&user=at&with_deleted=culpa" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/beatmapsets/discussions/posts"
);

const params = {
    "beatmapset_discussion_id": "similique",
    "limit": "17",
    "page": "2",
    "sort": "cupiditate",
    "types[]": "voluptatum",
    "user": "at",
    "with_deleted": "culpa",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





    



Request

    

        GET
        /beatmapsets/discussions/posts
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
Query Parameters

                    

            beatmapset_discussion_id  
string 
optional  
                
    


id of the BeatmapsetDiscussion.

        

                    

            limit  
integer 
optional  
                
    


Maximum number of results.

        

                    

            page  
integer 
optional  
                
    


Search result page.

        

                    

            sort  
string 
optional  
                
    


id_desc for newest first; id_asc for oldest first. Defaults to id_desc.

        

                    

            types[]  
string 
optional  
                
    


first, reply, system are the valid values. Defaults to reply.

        

                    

            user  
string 
optional  
                
    


The id of the User.

        

                    

            with_deleted  
string 
optional  
                
    


This param has no effect as api calls do not currently receive group permissions.

        

    




Response Format







Field
Type
Description






beatmapsets
Beatmapset





cursor_string
CursorString





posts
BeatmapsetDiscussionPost[]





users
User






                    
Get Beatmapset Discussion Votes




    
            OAuth
            public
    



Returns the votes given to beatmapset discussions.




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/beatmapsets/discussions/votes?beatmapset_discussion_id=quidem&limit=8&page=5&receiver=velit&score=dolores&sort=vitae&user=illo&with_deleted=perferendis" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/beatmapsets/discussions/votes"
);

const params = {
    "beatmapset_discussion_id": "quidem",
    "limit": "8",
    "page": "5",
    "receiver": "velit",
    "score": "dolores",
    "sort": "vitae",
    "user": "illo",
    "with_deleted": "perferendis",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





    



Request

    

        GET
        /beatmapsets/discussions/votes
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
Query Parameters

                    

            beatmapset_discussion_id  
string 
optional  
                
    


id of the BeatmapsetDiscussion.

        

                    

            limit  
integer 
optional  
                
    


Maximum number of results.

        

                    

            page  
integer 
optional  
                
    


Search result page.

        

                    

            receiver  
string 
optional  
                
    


The id of the User receiving the votes.

        

                    

            score  
string 
optional  
                
    


1 for up vote, -1 for down vote.

        

                    

            sort  
string 
optional  
                
    


id_desc for newest first; id_asc for oldest first. Defaults to id_desc.

        

                    

            user  
string 
optional  
                
    


The id of the User giving the votes.

        

                    

            with_deleted  
string 
optional  
                
    


This param has no effect as api calls do not currently receive group permissions.

        

    




Response Format







Field
Type
Description






cursor_string
CursorString





discussions
BeatmapsetDiscussion





users
User





votes
BeatmapsetDiscussionVote[]






                    
Get Beatmapset Discussions




    
            OAuth
            public
    



Returns a list of beatmapset discussions.




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/beatmapsets/discussions?beatmap_id=reprehenderit&beatmapset_id=quia&beatmapset_status=ipsam&limit=11&message_types%5B%5D=veniam&only_unresolved=sit&page=15&sort=earum&user=enim&with_deleted=ex" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/beatmapsets/discussions"
);

const params = {
    "beatmap_id": "reprehenderit",
    "beatmapset_id": "quia",
    "beatmapset_status": "ipsam",
    "limit": "11",
    "message_types[]": "veniam",
    "only_unresolved": "sit",
    "page": "15",
    "sort": "earum",
    "user": "enim",
    "with_deleted": "ex",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





    



Request

    

        GET
        /beatmapsets/discussions
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
Query Parameters

                    

            beatmap_id  
string 
optional  
                
    


id of the Beatmap.

        

                    

            beatmapset_id  
string 
optional  
                
    


id of the Beatmapset.

        

                    

            beatmapset_status  
string 
optional  
                
    


One of all, ranked, qualified, disqualified, never_qualified. Defaults to all. TODO: better descriptions.

        

                    

            limit  
integer 
optional  
                
    


Maximum number of results.

        

                    

            message_types[]  
string 
optional  
                
    


suggestion, problem, mapper_note, praise, hype, review. Blank defaults to all types. TODO: better descriptions.

        

                    

            only_unresolved  
string 
optional  
                
    


true to show only unresolved issues; false, otherwise. Defaults to false.

        

                    

            page  
integer 
optional  
                
    


Search result page.

        

                    

            sort  
string 
optional  
                
    


id_desc for newest first; id_asc for oldest first. Defaults to id_desc.

        

                    

            user  
string 
optional  
                
    


The id of the User.

        

                    

            with_deleted  
string 
optional  
                
    


This param has no effect as api calls do not currently receive group permissions.

        

                    

            cursor_string  
string 
optional  
                
    


CursorString for pagination.

        

    




Response Format







Field
Type
Description






beatmaps
BeatmapExtended[]
List of beatmaps associated with the discussions returned.




cursor_string
CursorString





discussions
BeatmapsetDiscussion[]
List of discussions according to sort order.




included_discussions
BeatmapsetDiscussion[]
Additional discussions related to discussions.




reviews_config.max_blocks
integer
Maximum number of blocks allowed in a review.




users
User[]
List of users associated with the discussions returned.





                
Beatmapsets


    

                                



    
            OAuth
            public
    






Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/beatmapsets/search" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/beatmapsets/search"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





    



Request

    

        GET
        /beatmapsets/search
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
Query Parameters

                    

            cursor_string  
string 
optional  
                
    


CursorString for pagination.

        

    




                    
GET api/v2/beatmapsets/lookup




    
            OAuth
            public
    






Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/beatmapsets/lookup" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/beatmapsets/lookup"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





    



Request

    

        GET
        /beatmapsets/lookup
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

    




                    
GET api/v2/beatmapsets/{beatmapset}




    
            OAuth
            public
    






Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/beatmapsets/fuga" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/beatmapsets/fuga"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





    



Request

    

        GET
        /beatmapsets/{beatmapset}
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            beatmapset  
string 
  
                
    


The beatmapset.

        

    




                    
GET api/v2/beatmapsets/{beatmapset}/download




    
            OAuth
            lazer
    






Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/beatmapsets/ipsam/download" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/beatmapsets/ipsam/download"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





    



Request

    

        GET
        /beatmapsets/{beatmapset}/download
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            beatmapset  
string 
  
                
    


The beatmapset.

        

    




                
Changelog


    

                                
Get Changelog Build




    
    



Returns details of the specified build.




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/changelog/stable40/20210520.2" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/changelog/stable40/20210520.2"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





            

            
Example response (200):

        

                
{
    "id": 5778,
    "version": "20210520.2",
    "display_version": "20210520.2",
    "users": 22093,
    "created_at": "2021-05-20T14:28:04+00:00",
    "update_stream": {
        "id": 5,
        "name": "stable40",
        "display_name": "Stable",
        "is_featured": true
    },
    "changelog_entries": [
        {
            "id": null,
            "repository": null,
            "github_pull_request_id": null,
            "github_url": null,
            "url": "https://osu.ppy.sh/home/news/2021-05-20-spring-fanart-contest-results",
            "type": "fix",
            "category": "Misc",
            "title": "Spring is here!",
            "message_html": "<div class='changelog-md'><p class=\"changelog-md__paragraph\">New seasonal backgrounds ahoy! Amazing work by the artists.</p>\n</div>",
            "major": true,
            "created_at": "2021-05-20T10:56:49+00:00",
            "github_user": {
                "display_name": "peppy",
                "github_url": null,
                "github_username": null,
                "id": null,
                "osu_username": "peppy",
                "user_id": 2,
                "user_url": "https://osu.ppy.sh/users/2"
            }
        }
    ],
    "versions": {
        "previous": {
            "id": 5774,
            "version": "20210519.3",
            "display_version": "20210519.3",
            "users": 10,
            "created_at": "2021-05-19T11:51:48+00:00",
            "update_stream": {
                "id": 5,
                "name": "stable40",
                "display_name": "Stable",
                "is_featured": true
            }
        }
    }
}
 

    



Request

    

        GET
        /changelog/{stream}/{build}
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            stream  
string 
  
                
    


Update stream name.

        

            

            build  
string 
  
                
    


Build version.

        

    




Response Format


A Build with changelog_entries, changelog_entries.github_user, and versions included.

                    
Get Changelog Listing




    
    



Returns a listing of update streams, builds, and changelog entries.




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/changelog?message_formats%5B%5D=suscipit" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/changelog"
);

const params = {
    "message_formats[]": "suscipit",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





            

            
Example response (200):

        

                
{
  "streams": [
    {
      "id": 5,
      "name": "stable40",
      "display_name": "Stable",
      "is_featured": true,
      "latest_build": {
        "id": 5778,
        "version": "20210520.2",
        "display_version": "20210520.2",
        "users": 23683,
        "created_at": "2021-05-20T14:28:04+00:00",
        "update_stream": {
          "id": 5,
          "name": "stable40",
          "display_name": "Stable",
          "is_featured": true
        }
      },
      "user_count": 23965
    },
    // ...
  ],
  "builds": [
    {
      "id": 5823,
      "version": "2021.619.1",
      "display_version": "2021.619.1",
      "users": 0,
      "created_at": "2021-06-19T08:30:45+00:00",
      "update_stream": {
        "id": 7,
        "name": "lazer",
        "display_name": "Lazer",
        "is_featured": false
      },
      "changelog_entries": [
        {
          "id": 12925,
          "repository": "ppy/osu",
          "github_pull_request_id": 13572,
          "github_url": "https://github.com/ppy/osu/pull/13572",
          "url": null,
          "type": "fix",
          "category": "Reliability",
          "title": "Fix game crashes due to attempting localisation load for unsupported locales",
          "message_html": null,
          "major": true,
          "created_at": "2021-06-19T08:09:39+00:00",
          "github_user": {
            "display_name": "bdach",
            "github_url": "https://github.com/bdach",
            "github_username": "bdach",
            "id": 218,
            "osu_username": null,
            "user_id": null,
            "user_url": null
          }
        }
      ]
    },
    // ...
  ],
  "search": {
    "stream": null,
    "from": null,
    "to": null,
    "max_id": null,
    "limit": 21
  }
}
 

    



Request

    

        GET
        /changelog
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
Query Parameters

                    

            from  
string 
optional  
                
    


Minimum build version.

        

                    

            max_id  
integer 
optional  
                
    


Maximum build ID.

        

                    

            stream  
string 
optional  
                
    


Stream name to return builds from.

        

                    

            to  
string 
optional  
                
    


Maximum build version.

        

                    

            message_formats[]  
string 
optional  
                
    


html, markdown. Default to both.

        

    




Response Format






Field
Type
Notes






builds
Build[]
Includes changelog_entries, changelog_entries.github_user, and changelog entry message in requested formats.




search.from
string?
from input.




search.limit
integer
Always 21.




search.max_id
integer?
max_id input.




search.stream
string?
stream input.




search.to
string?
to input.




streams
UpdateStream[]
Always contains all available streams. Includes latest_build and user_count.





                    
Lookup Changelog Build




    
    



Returns details of the specified build.




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/changelog/20210520.2?message_formats%5B%5D=dolorem" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/changelog/20210520.2"
);

const params = {
    "message_formats[]": "dolorem",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





            

            
Example response (200):

        

                
See "Get Changelog Build" response.
 

    



Request

    

        GET
        /changelog/{changelog}
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            changelog  
string 
  
                
    


Build version, update stream name, or build ID.

        

        
Query Parameters

                    

            key  
string 
optional  
                
    


Unset to query by build version or stream name, or id to query by build ID.

        

                    

            message_formats[]  
string 
optional  
                
    


html, markdown. Default to both.

        

    




Response Format


See Get Changelog Build.

                
Chat


    

                                
Chat Keepalive




            requires user
    
            OAuth
            chat.read
    



Request periodically to reset chat activity timeout. Also returns an updated list of recent silences.


See Public channels and activity timeout




Example request:





    
curl --request POST \
    "https://osu.ppy.sh/api/v2/chat/ack?history_since=5" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/chat/ack"
);

const params = {
    "history_since": "5",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());









Request

    

        POST
        /chat/ack
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
Query Parameters

                    

            history_since  
integer 
optional  
                
    


UserSilences after the specified id to return.
This field is preferred and takes precedence over since.

        

                    

            since  
integer 
optional  
                
    


UserSilences after the specified ChatMessage.message_id to return.

        

    




Response Format






Field
Type






silences
UserSilence[]





                    
Create New PM




            requires user
    
            OAuth
            chat.write
    



This endpoint allows you to create a new PM channel.




Example request:





    
curl --request POST \
    "https://osu.ppy.sh/api/v2/chat/new" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"target_id\": 2,
    \"message\": \"nam\",
    \"is_action\": false,
    \"uuid\": \"some-uuid-string\"
}"






    
const url = new URL(
    "https://osu.ppy.sh/api/v2/chat/new"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "target_id": 2,
    "message": "nam",
    "is_action": false,
    "uuid": "some-uuid-string"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());





            

            
Example response (200):

        

                
{
  "channel": [
    {
      "channel_id": 1234,
      "current_user_attributes": {
        "can_message": true,
        "can_message_error": null,
        "last_read_id": 9150005005
      },
      "name": "peppy",
      "description": "",
      "type": "PM",
      "last_read_id": 9150005005,
      "last_message_id": 9150005005
    }
  ],
  "message": {
    "message_id": 9150005005,
    "sender_id": 102,
    "channel_id": 1234,
    "timestamp": "2018-07-06T06:33:42+00:00",
    "content": "i can haz featured artist plz?",
    "is_action": false,
    "uuid": "some-uuid-string",
    "sender": {
      "id": 102,
      "username": "nekodex",
      "profile_colour": "#333333",
      "avatar_url": "https://a.ppy.sh/102?1500537068",
      "country_code": "AU",
      "is_active": true,
      "is_bot": false,
      "is_online": true,
      "is_supporter": true
    }
  },
  "new_channel_id": 1234,
}
 

    



Request

    

        POST
        /chat/new
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
Body Parameters

    

            target_id  
integer 
  
                
    


user_id of user to start PM with

        

                

            message  
string 
  
                
    


message to send

        

                

            is_action  
boolean 
  
                
        
    


whether the message is an action

        

                

            uuid  
string 
optional  
                
    


client-side message identifier which will be sent back in response and websocket json.

        

    




Response Format






Field
Type






channel
The new ChatChannel




message
the sent ChatMessage




new_channel_id
Deprecated; channel_id of newly created ChatChannel






                    
Get Updates




            requires user
    
            OAuth
            lazer
    



Returns the list of channels the current User is in along with an updated list of UserSilences.




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/chat/updates?history_since=9" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/chat/updates"
);

const params = {
    "history_since": "9",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





            

            
Example response (200):

        

                
{
    "presence": [
        {
            "channel_id": 5,
            "current_user_attributes": {
                "can_message": true,
                "can_message_error": null,
                "last_read_id": 9150005005
            },
            "name": "#osu",
            "description": "The official osu! channel (english only).",
            "type": "public",
            "last_read_id": 9150005005,
            "last_message_id": 9150005005
        },
        {
            "channel_id": 12345,
            "current_user_attributes": {
                "can_message": true,
                "can_message_error": null,
                "last_read_id": 9150001235
            },
            "type": "PM",
            "name": "peppy",
            "icon": "https://a.ppy.sh/2?1519081077.png",
            "users": [
                2,
                102
            ],
            "last_read_id": 9150001235,
            "last_message_id": 9150001234
        }
    ],
    "silences": [
        {
            "id": 1,
            "user_id": 2
        }
    ]
}
 

    



Request

    

        GET
        /chat/updates
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
Query Parameters

                    

            history_since  
integer 
optional  
                
    


UserSilences after the specified id to return.
This field is preferred and takes precedence over since.

        

                    

            includes  
string[] 
optional  
                
        
    


List of fields from presence, silences to include in the response. Returns all if not specified.

        

                    

            since  
integer 
optional  
                
    


UserSilences after the specified ChatMessage.message_id to return.

        

    




Response Format






Field
Type






messages
This field is not used and will be removed.




presence
ChatChannel[]?




silences
UserSilence[]?





                    
Get Channel Messages




            requires user
    
            OAuth
            chat.read
    



This endpoint returns the chat messages for a specific channel.




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/chat/channels/15/messages?limit=8&since=14&until=5" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/chat/channels/15/messages"
);

const params = {
    "limit": "8",
    "since": "14",
    "until": "5",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





            

            
Example response (200):

        

                
[
    {
        "message_id": 9150005004,
        "sender_id": 2,
        "channel_id": 5,
        "timestamp": "2018-07-06T06:33:34+00:00",
        "content": "i am a lazerface",
        "is_action": 0,
        "sender": {
            "id": 2,
            "username": "peppy",
            "profile_colour": "#3366FF",
            "avatar_url": "https://a.ppy.sh/2?1519081077.png",
            "country_code": "AU",
            "is_active": true,
            "is_bot": false,
            "is_online": true,
            "is_supporter": true
        }
    },
    {
        "message_id": 9150005005,
        "sender_id": 102,
        "channel_id": 5,
        "timestamp": "2018-07-06T06:33:42+00:00",
        "content": "uh ok then",
        "is_action": 0,
        "sender": {
            "id": 102,
            "username": "nekodex",
            "profile_colour": "#333333",
            "avatar_url": "https://a.ppy.sh/102?1500537068",
            "country_code": "AU",
            "is_active": true,
            "is_bot": false,
            "is_online": true,
            "is_supporter": true
        }
    }
]
 

    



Request

    

        GET
        /chat/channels/{channel}/messages
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            channel  
integer 
  
                
    


The ID of the channel to retrieve messages for

        

        
Query Parameters

                    

            limit  
integer 
optional  
                
    


number of messages to return (max of 50)

        

                    

            since  
integer 
optional  
                
    


messages after the specified message id will be returned

        

                    

            until  
integer 
optional  
                
    


messages up to but not including the specified message id will be returned

        

    




Response Format


Returns an array of ChatMessage

                    
Send Message to Channel




            requires user
    
            OAuth
            chat.write
    



This endpoint returns the chat messages for a specific channel.




Example request:





    
curl --request POST \
    "https://osu.ppy.sh/api/v2/chat/channels/18/messages" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"message\": \"qui\",
    \"is_action\": true
}"






    
const url = new URL(
    "https://osu.ppy.sh/api/v2/chat/channels/18/messages"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "message": "qui",
    "is_action": true
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());





            

            
Example response (200):

        

                
{
    "message_id": 9150005004,
    "sender_id": 2,
    "channel_id": 5,
    "timestamp": "2018-07-06T06:33:34+00:00",
    "content": "i am a lazerface",
    "is_action": 0,
    "sender": {
        "id": 2,
        "username": "peppy",
        "profile_colour": "#3366FF",
        "avatar_url": "https://a.ppy.sh/2?1519081077.png",
        "country_code": "AU",
        "is_active": true,
        "is_bot": false,
        "is_online": true,
        "is_supporter": true
    }
}
 

    



Request

    

        POST
        /chat/channels/{channel}/messages
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            channel  
integer 
  
                
    


The channel_id of the channel to send message to

        

        
Body Parameters

    

            message  
string 
  
                
    


message to send

        

                

            is_action  
boolean 
  
                
        
    


whether the message is an action

        

    




Response Format


The sent ChatMessage


                    
Join Channel




            requires user
    
            OAuth
            chat.write_manage
    



This endpoint allows you to join a public or multiplayer channel.




Example request:





    
curl --request PUT \
    "https://osu.ppy.sh/api/v2/chat/channels/tempora/users/delectus" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/chat/channels/tempora/users/delectus"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "PUT",
    headers,
}).then(response => response.json());





            

            
Example response (200):

        

                
{
  "channel_id": 5,
  "current_user_attributes": {
    "can_message": true,
    "can_message_error": null
  },
  "description": "The official osu! channel (english only).",
  "icon": "https://a.ppy.sh/2?1519081077.png",
  "last_message_id": 1029,
  "moderated": false,
  "name": "#osu",
  "type": "public"
  "users": []
}
 

    



Request

    

        PUT
        /chat/channels/{channel}/users/{user}
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            channel  
string 
  
                
    


The channel.

        

            

            user  
string 
  
                
    


The user.

        

    




Response Format


Returns the joined ChatChannel.

                    
Leave Channel




            requires user
    
            OAuth
            chat.write_manage
    



This endpoint allows you to leave a public channel.




Example request:





    
curl --request DELETE \
    "https://osu.ppy.sh/api/v2/chat/channels/qui/users/provident" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/chat/channels/qui/users/provident"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());





            

            
Example response (204):

        

                
[Empty response]
 

    



Request

    

        DELETE
        /chat/channels/{channel}/users/{user}
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            channel  
string 
  
                
    


The channel.

        

            

            user  
string 
  
                
    


The user.

        

    




Response Format


empty response


                    
Mark Channel as Read




            requires user
    
            OAuth
            chat.read
    



This endpoint marks the channel as having being read up to the given message_id.




Example request:





    
curl --request PUT \
    "https://osu.ppy.sh/api/v2/chat/channels/architecto/mark-as-read/eligendi?channel_id=veritatis&message_id=hic" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/chat/channels/architecto/mark-as-read/eligendi"
);

const params = {
    "channel_id": "veritatis",
    "message_id": "hic",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "PUT",
    headers,
}).then(response => response.json());





            

            
Example response (204):

        

                
[Empty response]
 

    



Request

    

        PUT
        /chat/channels/{channel}/mark-as-read/{message}
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            channel  
string 
  
                
    


The channel.

        

            

            message  
string 
  
                
    


        

        
Query Parameters

                    

            channel_id  
string 
  
                
    


The channel_id of the channel to mark as read

        

                    

            message_id  
string 
  
                
    


The message_id of the message to mark as read up to

        

    




Response Format


empty response


                    
Get Channel List




            requires user
    
            OAuth
            chat.read
    



This endpoint returns a list of all joinable public channels.




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/chat/channels" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/chat/channels"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





            

            
Example response (200):

        

                
[
    {
        "channel_id": 5,
        "description": "The official osu! channel (english only).",
        "icon": "https://a.ppy.sh/2?1519081077.png",
        "moderated": false,
        "name": "#osu",
        "type": "public"
    }
]
 

    



Request

    

        GET
        /chat/channels
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

    




Response Format


Returns an array of ChatChannel

                    
Create Channel




            requires user
    
            OAuth
            chat.write_manage
    



Creates a new PM or announcement channel.
Rejoins the PM channel if it already exists.




Example request:





    
curl --request POST \
    "https://osu.ppy.sh/api/v2/chat/channels" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"target_id\": 2,
    \"type\": \"PM\"
}"






    
const url = new URL(
    "https://osu.ppy.sh/api/v2/chat/channels"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "target_id": 2,
    "type": "PM"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());





            

            
Example response (200):

        

                
{
    "channel_id": 1,
    "description": "best channel",
    "icon": "https://a.ppy.sh/2?1519081077.png",
    "moderated": false,
    "name": "#pm_1-2",
    "type": "PM",
    "recent_messages": [
        {
            "message_id": 1,
            "sender_id": 1,
            "channel_id": 1,
            "timestamp": "2020-01-01T00:00:00+00:00",
            "content": "Happy new year",
            "is_action": false,
            "sender": {
                "id": 2,
                "username": "peppy",
                "profile_colour": "#3366FF",
                "avatar_url": "https://a.ppy.sh/2?1519081077.png",
                "country_code": "AU",
                "is_active": true,
                "is_bot": false,
                "is_online": true,
                "is_supporter": true
            }
        }
    ]
}
 

    



Request

    

        POST
        /chat/channels
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
Body Parameters

    

        

            
                channel  
object 
optional  



channel details; required if type is ANNOUNCE.

            
                                                

                        name  
string 
optional  
                
    


the channel name; required if type is ANNOUNCE.

                    

                                                                

                        description  
string 
optional  
                
    


the channel description; required if type is ANNOUNCE.

                    

                                    

        

                

            message  
string 
optional  
                
    


message to send with the announcement; required if type is ANNOUNCE.

        

                

            target_id  
integer 
optional  
                
    


target user id; required if type is PM; ignored, otherwise.

        

                

            target_ids  
integer[] 
optional  
                
        
    


target user ids; required if type is ANNOUNCE; ignored, otherwise.

        

                

            type  
string 
  
                
    


channel type (currently only supports PM and ANNOUNCE)

        

    




Response Format


Returns ChatChannel with recent_messages attribute; recent_messages is deprecated and should not be used.

                    
Get Channel




            requires user
    
            OAuth
            chat.read
    



Gets details of a chat channel.




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/chat/channels/pariatur" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/chat/channels/pariatur"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





            

            
Example response (200):

        

                
{
    "channel": {
        "channel_id": 1337,
        "current_user_attributes": {
            "can_message": true,
            "can_message_error": null
        },
        "name": "test channel",
        "description": "wheeeee",
        "icon": "/images/layout/avatar-guest@2x.png",
        "type": "PM",
        "last_message_id": 9150005005,
        "moderated": false,
        "users": [
            2,
            102
        ]
    },
    "users": [
        {
            "id": 2,
            "username": "peppy",
            "profile_colour": "#3366FF",
            "avatar_url": "https://a.ppy.sh/2?1519081077.png",
            "country_code": "AU",
            "is_active": true,
            "is_bot": false,
            "is_deleted": false,
            "is_online": true,
            "is_supporter": true
        },
        {
            "id": 102,
            "username": "lambchop",
            "profile_colour": "#3366FF",
            "icon": "/images/layout/avatar-guest@2x.png",
            "country_code": "NZ",
            "is_active": true,
            "is_bot": false,
            "is_deleted": false,
            "is_online": false,
            "is_supporter": false
        }
    ]
}
 

    



Request

    

        GET
        /chat/channels/{channel}
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            channel  
string 
  
                
    


The channel.

        

    




Response Format






Field
Type
Description






channel
ChatChannel





users
User
Users are only visible for PM channels.





                
Comments


    

                                
Get Comments




    
    



Returns a list comments and their replies up to 2 levels deep.




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/comments?commentable_type=beatmapset&commentable_id=1&parent_id=1&sort=new" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/comments"
);

const params = {
    "commentable_type": "beatmapset",
    "commentable_id": "1",
    "parent_id": "1",
    "sort": "new",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





    



Request

    

        GET
        /comments
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
Query Parameters

                    

            after  
string 
optional  
                
    


Return comments which come after the specified comment id as per sort option.

        

                    

            commentable_type  
string 
optional  
                
    


The type of resource to get comments for.

        

                    

            commentable_id  
string 
optional  
                
    


The id of the resource to get comments for.

        

                    

            cursor  
string 
optional  
                
    


Pagination option. See CommentSort for detail. The format follows Cursor except it's not currently included in the response.

        

                    

            parent_id  
string 
optional  
                
    


Limit to comments which are reply to the specified id. Specify 0 to get top level comments.

        

                    

            sort  
string 
optional  
                
    


Sort option as defined in CommentSort. Defaults to new for guests and user-specified default when authenticated.

        

    




Response Format


Returns CommentBundle.


pinned_comments is only included when commentable_type and commentable_id are specified.

                    
Post a new comment




            requires user
    
            OAuth
            lazer
    



Posts a new comment to a comment thread.




Example request:





    
curl --request POST \
    "https://osu.ppy.sh/api/v2/comments" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/comments"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());









Request

    

        POST
        /comments
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
Query Parameters

                    

            comment.commentable_id  
string 
optional  
                
    


Resource ID the comment thread is attached to

        

                    

            comment.commentable_type  
string 
optional  
                
    


Resource type the comment thread is attached to

        

                    

            comment.message  
string 
optional  
                
    


Text of the comment

        

                    

            comment.parent_id  
string 
optional  
                
    


The id of the comment to reply to, null if not a reply

        

    




Response Format


Returns CommentBundle

                    
Get a Comment




    
    



Gets a comment and its replies up to 2 levels deep.




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/comments/consequatur" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/comments/consequatur"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





    



Request

    

        GET
        /comments/{comment}
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            comment  
string 
  
                
    


The comment.

        

    




Response Format


Returns CommentBundle

                    
Edit Comment




            requires user
    
            OAuth
            lazer
    



Edit an existing comment.




Example request:





    
curl --request PUT \
    "https://osu.ppy.sh/api/v2/comments/ratione" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/comments/ratione"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "PUT",
    headers,
}).then(response => response.json());









Request

    

        PUT
        /comments/{comment}
    

    

        PATCH
        /comments/{comment}
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            comment  
string 
  
                
    


The comment.

        

        
Query Parameters

                    

            comment.message  
string 
optional  
                
    


New text of the comment

        

    




Response Format


Returns CommentBundle

                    
Delete Comment




            requires user
    
            OAuth
            lazer
    



Deletes the specified comment.




Example request:





    
curl --request DELETE \
    "https://osu.ppy.sh/api/v2/comments/non" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/comments/non"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());









Request

    

        DELETE
        /comments/{comment}
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            comment  
string 
  
                
    


The comment.

        

    




Response Format


Returns CommentBundle

                    
Add Comment vote




            requires user
    
            OAuth
            lazer
    



Upvotes a comment.




Example request:





    
curl --request POST \
    "https://osu.ppy.sh/api/v2/comments/id/vote" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/comments/id/vote"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());









Request

    

        POST
        /comments/{comment}/vote
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            comment  
string 
  
                
    


The comment.

        

    




Response Format


Returns CommentBundle

                    
Remove Comment vote




            requires user
    
            OAuth
            lazer
    



Un-upvotes a comment.




Example request:





    
curl --request DELETE \
    "https://osu.ppy.sh/api/v2/comments/temporibus/vote" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/comments/temporibus/vote"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());









Request

    

        DELETE
        /comments/{comment}/vote
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            comment  
string 
  
                
    


The comment.

        

    




Response Format


Returns CommentBundle

                
Events


    

                                
Get Events




    
            OAuth
            public
    



Returns a collection of Events in order of creation time.




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/events" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/events"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





            

            
Example response (200):

        

                
{
  events: [
    {
      created_at: "2022-12-08T02:02:51+00:00",
      id: 57,
      type: "achievement",
      achievement: { ... },
      user: { ... }
    },
    ...
  ],
  cursor_string: "eyJldmVudF9pZCI6OH0"
}
 

    



Request

    

        GET
        /events
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
Query Parameters

                    

            sort  
string 
optional  
                
    


Sorting option. Valid values are id_desc (default) and id_asc.

        

                    

            cursor_string  
string 
optional  
                
    


CursorString for pagination.

        

    




Response Format






Field
Type






cursor_string
CursorString




events
Event[]





                
Forum


    

                                
Reply Topic




            requires user
    
            OAuth
            forum.write
    



Create a post replying to the specified topic.




Example request:





    
curl --request POST \
    "https://osu.ppy.sh/api/v2/forums/topics/1/reply" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"body\": \"hello\"
}"






    
const url = new URL(
    "https://osu.ppy.sh/api/v2/forums/topics/1/reply"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "body": "hello"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());









Request

    

        POST
        /forums/topics/{topic}/reply
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            topic  
integer 
  
                
    


Id of the topic to be replied to.

        

        
Body Parameters

    

            body  
string 
  
                
    


Content of the reply post.

        

    




Response Format


ForumPost with body included.

                    
Create Topic




            requires user
    
            OAuth
            forum.write
    



Create a new topic.




Example request:





    
curl --request POST \
    "https://osu.ppy.sh/api/v2/forums/topics" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"body\": \"hello\",
    \"forum_id\": 1,
    \"title\": \"untitled\",
    \"with_poll\": true,
    \"forum_topic_poll[options]\": \"item A...\",
    \"forum_topic_poll[title]\": \"my poll\"
}"






    
const url = new URL(
    "https://osu.ppy.sh/api/v2/forums/topics"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "body": "hello",
    "forum_id": 1,
    "title": "untitled",
    "with_poll": true,
    "forum_topic_poll[options]": "item A...",
    "forum_topic_poll[title]": "my poll"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());









Request

    

        POST
        /forums/topics
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
Body Parameters

    

            body  
string 
  
                
    


Content of the topic.

        

                

            forum_id  
integer 
  
                
    


Forum to create the topic in.

        

                

            title  
string 
  
                
    


Title of the topic.

        

                

            with_poll  
boolean 
optional  
                
        
    


Enable this to also create poll in the topic (default: false).

        

                

            forum_topic_poll[hide_results]  
boolean 
optional  
                
        
    


Enable this to hide result until voting period ends (default: false).

        

                

            forum_topic_poll[length_days]  
integer 
optional  
                
    


Number of days for voting period. 0 means the voting will never ends (default: 0). This parameter is required if hide_results option is enabled.

        

                

            forum_topic_poll[max_options]  
integer 
optional  
                
    


Maximum number of votes each user can cast (default: 1).

        

                

            forum_topic_poll[options]  
string 
  
                
    


Newline-separated list of voting options. BBCode is supported.

        

                

            forum_topic_poll[title]  
string 
  
                
    


Title of the poll.

        

                

            forum_topic_poll[vote_change]  
boolean 
optional  
                
        
    


Enable this to allow user to change their votes (default: false).

        

    




Response Format






Field
Type
Includes






topic
ForumTopic





post
ForumPost
body





                    
Get Topic and Posts




    
            OAuth
            public
    



Get topic and its posts.




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/forums/topics/1" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/forums/topics/1"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





            

            
Example response (200):

        

                
{
    "topic": {
        "id": 1,
        "...": "..."
    },
    "posts": [
        {
            "id": 1,
            "...": "..."
        },
        {
            "id": 2,
            "...": "..."
        }
    ],
    "cursor_string": "eyJoZWxsbyI6IndvcmxkIn0",
    "sort": "id_asc"
}
 

    



Request

    

        GET
        /forums/topics/{topic}
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            topic  
integer 
  
                
    


Id of the topic.

        

        
Query Parameters

                    

            sort  
string 
optional  
                
    


Post sorting option. Valid values are id_asc (default) and id_desc.

        

                    

            limit  
integer 
optional  
                
    


Maximum number of posts to be returned (20 default, 50 at most).

        

                    

            start  
string 
optional  
                
    


First post id to be returned with sort set to id_asc. This parameter is ignored if cursor_string is specified.

        

                    

            end  
string 
optional  
                
    


First post id to be returned with sort set to id_desc. This parameter is ignored if cursor_string is specified.

        

                    

            cursor_string  
string 
optional  
                
    


CursorString for pagination.

        

    




Response Format






Field
Type
Notes






cursor_string
CursorString





posts
ForumPost[]
Includes body.




search

Parameters used for current request excluding cursor.




topic
ForumTopic






                    
Edit Topic




    
            OAuth
            forum.write
    



Edit topic. Only title can be edited through this endpoint.




Example request:





    
curl --request PUT \
    "https://osu.ppy.sh/api/v2/forums/topics/1" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"forum_topic[topic_title]\": \"titled\"
}"






    
const url = new URL(
    "https://osu.ppy.sh/api/v2/forums/topics/1"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "forum_topic[topic_title]": "titled"
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());









Request

    

        PUT
        /forums/topics/{topic}
    

    

        PATCH
        /forums/topics/{topic}
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            topic  
integer 
  
                
    


Id of the topic.

        

        
Body Parameters

    

            forum_topic[topic_title]  
string 
optional  
                
    


New topic title.

        

    




Response Format


The edited ForumTopic.

                    
Edit Post




    
            OAuth
            forum.write
    



Edit specified forum post.




Example request:





    
curl --request PUT \
    "https://osu.ppy.sh/api/v2/forums/posts/1" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"body\": \"hello\"
}"






    
const url = new URL(
    "https://osu.ppy.sh/api/v2/forums/posts/1"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "body": "hello"
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());









Request

    

        PUT
        /forums/posts/{post}
    

    

        PATCH
        /forums/posts/{post}
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            post  
integer 
  
                
    


Id of the post.

        

        
Body Parameters

    

            body  
string 
  
                
    


New post content in BBCode format.

        

    




Response Format


ForumPost with body included.

                
Home


    

                                



    
            OAuth
            public
    



Searches users and wiki pages.




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/search?mode=all&query=hello&page=1" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/search"
);

const params = {
    "mode": "all",
    "query": "hello",
    "page": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





    



Request

    

        GET
        /search
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
Query Parameters

                    

            mode  
string 
optional  
                
    


Either all, user, or wiki_page. Default is all.

        

                    

            query  
string 
optional  
                
    


Search keyword.

        

                    

            page  
integer 
optional  
                
    


Search result page. Ignored for mode all.

        

    




Response Format






Field
Type
Description






user
SearchResult<User>?
For all or user mode. Only first 100 results are accessible




wiki_page
SearchResult<WikiPage>?
For all or wiki_page mode






SearchResult<T>






Field
Type
Description






data
T[]





total
integer






                
Matches


    

                                
Get Matches Listing




    
            OAuth
            public
    



Returns a list of matches.




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/matches" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/matches"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





            

            
Example response (200):

        

                
{
    "matches": [
        {
            "id": 114428685,
            "start_time": "2024-06-25T00:55:30+00:00",
            "end_time": null,
            "name": "peppy's game"
        },
        // ...
    ],
    "params": {
        "limit": 50,
        "sort": "id_desc"
    },
    "cursor": {
        "match_id": 114428685
    },
    "cursor_string": "eyJtYXRjaF9pZCI6MTE0NDI4Njg1fQ"
}
 

    



Request

    

        GET
        /matches
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
Query Parameters

                    

            limit  
integer 
optional  
                
    


Maximum number of matches (50 default, 1 minimum, 50 maximum).

        

                    

            sort  
string 
optional  
                
    


id_desc for newest first; id_asc for oldest first. Defaults to id_desc.

        

                    

            cursor_string  
string 
optional  
                
    


CursorString for pagination.

        

    




Response Format






Field
Type
Notes






cursor
Cursor





cursor_string
CursorString





matches
Match[]





params.limit
integer





params.sort
string






                    
Get Match




    
            OAuth
            public
    



Returns details of the specified match.




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/matches/" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/matches/"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





            

            
Example response (200):

        

                
{
    "match": {
        "id": 16155689,
        "start_time": "2015-05-16T09:44:51+00:00",
        "end_time": "2015-05-16T10:55:08+00:00",
        "name": "CWC 2015: (Australia) vs (Poland)"
    },
    "events": [
        {
            "id": 484385927,
            "detail": {
                "type": "match-created"
            },
            "timestamp": "2015-05-16T09:44:51+00:00",
            "user_id": null
        },
        // ...
    ],
    "users": [],
    "first_event_id": 484385927,
    "latest_event_id": 484410607,
    "current_game_id": null
}
 

    



Request

    

        GET
        /matches/{match}
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            match  
integer 
  
                
    


Match ID.

        

        
Query Parameters

                    

            before  
integer 
optional  
                
    


Filter for match events before the specified MatchEvent.id.

        

                    

            after  
integer 
optional  
                
    


Filter for match events after the specified MatchEvent.id.

        

                    

            limit  
integer 
optional  
                
    


Maximum number of match events (100 default, 1 minimum, 101 maximum).

        

    




Response Format






Field
Type
Notes






match
Match





events
MatchEvent[]





users
User[]
Includes country.




first_event_id
integer
ID of the first MatchEvent in the match.




latest_event_id
integer
ID of the lastest MatchEvent in the match.





                
Multiplayer


    

                                
Get User High Score




            requires user
    
            OAuth
            lazer
    



Returns detail of highest score of specified user and the surrounding scores.




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/rooms/2/playlist/2/scores/users/7" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/rooms/2/playlist/2/scores/users/7"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





    



Request

    

        GET
        /rooms/{room}/playlist/{playlist}/scores/users/{user}
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            room  
integer 
  
                
    


Id of the room.

        

            

            playlist  
integer 
  
                
    


Id of the playlist item.

        

            

            user  
integer 
  
                
    


User id.

        

    




Response Format


Returns Score object.

                    
Get Scores




    
            OAuth
            public
    



Returns a list of scores for specified playlist item.




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/rooms/13/playlist/15/scores?limit=15&sort=nobis" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/rooms/13/playlist/15/scores"
);

const params = {
    "limit": "15",
    "sort": "nobis",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





    



Request

    

        GET
        /rooms/{room}/playlist/{playlist}/scores
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            room  
integer 
  
                
    


Id of the room.

        

            

            playlist  
integer 
  
                
    


Id of the playlist item.

        

        
Query Parameters

                    

            limit  
integer 
optional  
                
    


Number of scores to be returned.

        

                    

            sort  
string 
optional  
                
    


MultiplayerScoresSort parameter.

        

                    

            cursor_string  
string 
optional  
                
    


CursorString for pagination.

        

    




Response Format


Returns MultiplayerScores object.

                    
Get a Score




            requires user
    
            OAuth
            lazer
    



Returns detail of specified score and the surrounding scores.




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/rooms/15/playlist/1/scores/2" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/rooms/15/playlist/1/scores/2"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





    



Request

    

        GET
        /rooms/{room}/playlist/{playlist}/scores/{score}
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            room  
integer 
  
                
    


Id of the room.

        

            

            playlist  
integer 
  
                
    


Id of the playlist item.

        

            

            score  
integer 
  
                
    


Id of the score.

        

    




Response Format


Returns Score object.

                    
Get Multiplayer Rooms




            requires user
    
            OAuth
            public
    



Returns a list of multiplayer rooms.




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/rooms" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/rooms"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





    



Request

    

        GET
        /rooms
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
Query Parameters

                    

            limit  
integer 
optional  
                
    


Maximum number of results.

        

                    

            mode  
string 
optional  
                
    


Filter mode; active (default), all, ended, participated, owned.

        

                    

            season_id  
string 
optional  
                
    


Season ID to return Rooms from.

        

                    

            sort  
string 
optional  
                
    


Sort order; ended, created.

        

                    

            type_group  
string 
optional  
                
    


playlists (default) or realtime.

        

    




                
News


    

                                
Get News Listing




    
    



Returns a list of news posts and related metadata.




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/news" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/news"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





            

            
Example response (200):

        

                
{
  "news_posts": [
    {
      "id": 964,
      "author": "RockRoller",
      "edit_url": "https://github.com/ppy/osu-wiki/tree/master/news/2021-05-27-skinning-contest-results.md",
      "first_image": "https://i.ppy.sh/d431ff921955d5c8792dc9bae40ac082d4e53131/68747470733a2f2f6f73752e7070792e73682f77696b692f696d616765732f7368617265642f6e6577732f323032312d30352d32372d736b696e6e696e672d636f6e746573742d726573756c74732f736b696e6e696e675f636f6e746573745f62616e6e65722e6a7067",
      "published_at": "2021-05-27T12:00:00+00:00",
      "updated_at": "2021-05-28T17:11:35+00:00",
      "slug": "2021-05-27-skinning-contest-results",
      "title": "Skinning Contest: Results Out",
      "preview": "The ship full of skins is now back with your votes. Check out the results for our first-ever official skinning contest right here!"
    },
    // ...
  ],
  "news_sidebar": {
    "current_year": 2021,
    "news_posts": [
      {
        "id": 964,
        "author": "RockRoller",
        "edit_url": "https://github.com/ppy/osu-wiki/tree/master/news/2021-05-27-skinning-contest-results.md",
        "first_image": "https://i.ppy.sh/d431ff921955d5c8792dc9bae40ac082d4e53131/68747470733a2f2f6f73752e7070792e73682f77696b692f696d616765732f7368617265642f6e6577732f323032312d30352d32372d736b696e6e696e672d636f6e746573742d726573756c74732f736b696e6e696e675f636f6e746573745f62616e6e65722e6a7067",
        "published_at": "2021-05-27T12:00:00+00:00",
        "updated_at": "2021-05-28T17:11:35+00:00",
        "slug": "2021-05-27-skinning-contest-results",
        "title": "Skinning Contest: Results Out"
      },
      // ...
    ],
    "years": [2021, 2020, 2019, 2018, 2017, 2016, 2015, 2014, 2013]
  },
  "search": {
    "limit": 12,
    "sort": "published_desc"
  },
  "cursor_string": "WyJodHRwczpcL1wvd3d3LnlvdXR1YmUuY29tXC93YXRjaD92PWRRdzR3OVdnWGNRIl0"
}
 

    



Request

    

        GET
        /news
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
Query Parameters

                    

            limit  
integer 
optional  
                
    


Maximum number of posts (12 default, 1 minimum, 21 maximum).

        

                    

            year  
integer 
optional  
                
    


Year to return posts from.

        

                    

            cursor_string  
string 
optional  
                
    


CursorString for pagination.

        

    




Response Format






Field
Type
Notes






cursor_string
CursorString





news_posts
NewsPost[]
Includes preview.




news_sidebar.current_year
integer
Year of the first post's publish time, or current year if no posts returned.




news_sidebar.news_posts
NewsPost[]
All posts published during current_year.




news_sidebar.years
integer[]
All years during which posts have been published.




search.limit
integer
Clamped limit input.




search.sort
string
Always published_desc.






                    
Get News Post




    
    



Returns details of the specified news post.




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/news/2021-04-27-results-a-labour-of-love" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/news/2021-04-27-results-a-labour-of-love"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





            

            
Example response (200):

        

                
{
    "id": 943,
    "author": "pishifat",
    "edit_url": "https://github.com/ppy/osu-wiki/tree/master/news/2021-04-27-results-a-labour-of-love.md",
    "first_image": "https://i.ppy.sh/65c9c2eb2f8d9bc6008b95aba7d0ef45e1414c1e/68747470733a2f2f6f73752e7070792e73682f77696b692f696d616765732f7368617265642f6e6577732f323032302d31312d33302d612d6c61626f75722d6f662d6c6f76652f616c6f6c5f636f7665722e6a7067",
    "published_at": "2021-04-27T20:00:00+00:00",
    "updated_at": "2021-04-27T20:25:57+00:00",
    "slug": "2021-04-27-results-a-labour-of-love",
    "title": "Results - A Labour of Love",
    "content": "<div class='osu-md osu-md--news'>...</div>",
    "navigation": {
        "newer": {
            "id": 944,
            "author": "pishifat",
            "edit_url": "https://github.com/ppy/osu-wiki/tree/master/news/2021-04-28-new-featured-artist-emilles-moonlight-serenade.md",
            "first_image": "https://i.ppy.sh/7e22cc5f4755c21574d999d8ce3a2f40a3268e84/68747470733a2f2f6173736574732e7070792e73682f617274697374732f3136302f6865616465722e6a7067",
            "published_at": "2021-04-28T08:00:00+00:00",
            "updated_at": "2021-04-28T09:51:28+00:00",
            "slug": "2021-04-28-new-featured-artist-emilles-moonlight-serenade",
            "title": "New Featured Artist: Emille's Moonlight Serenade"
        },
        "older": {
            "id": 942,
            "author": "pishifat",
            "edit_url": "https://github.com/ppy/osu-wiki/tree/master/news/2021-04-24-new-featured-artist-grynpyret.md",
            "first_image": "https://i.ppy.sh/acdce813b71371b95e8240f9249c916285fdc5a0/68747470733a2f2f6173736574732e7070792e73682f617274697374732f3135392f6865616465722e6a7067",
            "published_at": "2021-04-24T08:00:00+00:00",
            "updated_at": "2021-04-24T10:23:59+00:00",
            "slug": "2021-04-24-new-featured-artist-grynpyret",
            "title": "New Featured Artist: Grynpyret"
        }
    }
}
 

    



Request

    

        GET
        /news/{news}
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            news  
string 
  
                
    


News post slug or ID.

        

        
Query Parameters

                    

            key  
string 
optional  
                
    


Unset to query by slug, or id to query by ID.

        

    




Response Format


Returns a NewsPost with content and navigation included.

                
Notification


    

                                
Get Notifications




            requires user
    
            OAuth
            lazer
    



This endpoint returns a list of the user's unread notifications. Sorted descending by id with limit of 50.




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/notifications?max_id=ullam" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/notifications"
);

const params = {
    "max_id": "ullam",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





            

            
Example response (200):

        

                
{
    "has_more": true,
    "notifications": [
        {
            "id": 1,
            "name": "forum_topic_reply",
            "created_at": "2019-04-24T07:12:43+00:00",
            "object_type": "forum_topic",
            "object_id": 1,
            "source_user_id": 1,
            "is_read": false,
            "details": {
                "title": "A topic",
                "post_id": 2,
                "username": "User",
                "cover_url": "https://..."
            }
        }
    ],
    "unread_count": 100,
    "notification_endpoint": "wss://notify.ppy.sh"
}
 

    



Request

    

        GET
        /notifications
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
Query Parameters

                    

            max_id  
string 
optional  
                
    


Maximum id fetched. Can be used to load earlier notifications. Defaults to no limit (fetch latest notifications)

        

    




Response Format


Returns an object containing Notification and other related attributes.






Field
Type






has_more
boolean whether or not there are more notifications




notifications
array of Notification




unread_count
total unread notifications




notification_endpoint
url to connect to websocket server





                    
Mark Notifications as Read




            requires user
    
            OAuth
            lazer
    



This endpoint allows you to mark notifications read.




Example request:





    
curl --request POST \
    "https://osu.ppy.sh/api/v2/notifications/mark-read" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \






    
const url = new URL(
    "https://osu.ppy.sh/api/v2/notifications/mark-read"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());





            

            
Example response (204):

        

                
[Empty response]
 

    



Request

    

        POST
        /notifications/mark-read
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
Body Parameters

    

        

            
                identities  
object 
optional  



            
                                                

                        category  
string 
optional  
                
    


Notification category.

                    

                                                                

                        object_id  
string 
optional  
                
    


Id of the object triggered the notification.

                    

                                                                

                        object_type  
string 
optional  
                
    


Type of the object triggered the notification.

                    

                                    

        

                

        

            
                notifications  
object 
optional  



            
                                                

                        category  
string 
optional  
                
    


Notification category.

                    

                                                                

                        id  
integer 
optional  
                
    


Id of notifications to be marked as read.

                    

                                                                

                        object_id  
string 
optional  
                
    


Id of the object triggered the notification.

                    

                                                                

                        object_type  
string 
optional  
                
    


Type of the object triggered the notification.

                    

                                    

        

    




Response Format


empty response

                
OAuth Tokens


    

                                
Revoke current token




    
            OAuth
    



Revokes currently authenticated token.




Example request:





    
curl --request DELETE \
    "https://osu.ppy.sh/api/v2/oauth/tokens/current" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/oauth/tokens/current"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());





            

            
Example response (204):

        

                
[Empty response]
 

    



Request

    

        DELETE
        /oauth/tokens/current
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

    




                
Ranking


    

                                
Get Kudosu Ranking




    
            OAuth
            public
    



Gets the kudosu ranking.




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/rankings/kudosu?page=1" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/rankings/kudosu"
);

const params = {
    "page": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





    



Request

    

        GET
        /rankings/kudosu
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
Query Parameters

                    

            page  
integer 
optional  
                
    


Ranking page.

        

    




Response format






Field
Type
Description






ranking
User[]
Includes kudosu.





                    
Get Ranking




    
            OAuth
            public
    



Gets the current ranking for the specified type and game mode.




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/rankings/mania/performance?country=JP&filter=all&variant=4k" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/rankings/mania/performance"
);

const params = {
    "country": "JP",
    "filter": "all",
    "variant": "4k",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





    



Request

    

        GET
        /rankings/{mode}/{type}
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            mode  
string 
  
                
    


Ruleset.

        

            

            type  
string 
  
                
    


RankingType.

        

        
Query Parameters

                    

            country  
string 
optional  
                
    


Filter ranking by country code. Only available for type of performance.

        

                    

            cursor  
string 
optional  
                
    


Cursor.

        

                    

            filter  
string 
optional  
                
    


Either all (default) or friends.

        

                    

            spotlight  
string 
optional  
                
    


The id of the spotlight if type is charts. Ranking for latest spotlight will be returned if not specified.

        

                    

            variant  
string 
optional  
                
    


Filter ranking to specified mode variant. For mode of mania, it's either 4k or 7k. Only available for type of performance.

        

    




Response Format


Returns Rankings

                    
Get Spotlights




    
            OAuth
            public
    



Gets the list of spotlights.




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/spotlights" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/spotlights"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





    



Request

    

        GET
        /spotlights
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

    




Response Format


Returns Spotlights

                
Undocumented


    

                                
POST api/v2/session/verify




            requires user
    
            OAuth
    






Example request:





    
curl --request POST \
    "https://osu.ppy.sh/api/v2/session/verify" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/session/verify"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());









Request

    

        POST
        /session/verify
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

    




                    
POST api/v2/session/verify/reissue




            requires user
    
            OAuth
    






Example request:





    
curl --request POST \
    "https://osu.ppy.sh/api/v2/session/verify/reissue" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/session/verify/reissue"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());









Request

    

        POST
        /session/verify/reissue
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

    




                    
POST api/v2/beatmaps/{beatmap}/solo/scores




            requires user
    
            OAuth
            lazer
    






Example request:





    
curl --request POST \
    "https://osu.ppy.sh/api/v2/beatmaps/id/solo/scores" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/beatmaps/id/solo/scores"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());









Request

    

        POST
        /beatmaps/{beatmap}/solo/scores
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            beatmap  
string 
  
                
    


The beatmap.

        

    




                    
PUT api/v2/beatmaps/{beatmap}/solo/scores/{token}




            requires user
    
            OAuth
            lazer
    






Example request:





    
curl --request PUT \
    "https://osu.ppy.sh/api/v2/beatmaps/voluptatem/solo/scores/illum" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/beatmaps/voluptatem/solo/scores/illum"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "PUT",
    headers,
}).then(response => response.json());









Request

    

        PUT
        /beatmaps/{beatmap}/solo/scores/{token}
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            beatmap  
string 
  
                
    


The beatmap.

        

            

            token  
string 
  
                
    


        

    




                    
GET api/v2/beatmapsets/events




    
            OAuth
            public
    






Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/beatmapsets/events" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/beatmapsets/events"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





    



Request

    

        GET
        /beatmapsets/events
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

    




                    
POST api/v2/beatmapsets/{beatmapset}/favourites




            requires user
    
            OAuth
            lazer
    






Example request:





    
curl --request POST \
    "https://osu.ppy.sh/api/v2/beatmapsets/facilis/favourites" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/beatmapsets/facilis/favourites"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());









Request

    

        POST
        /beatmapsets/{beatmapset}/favourites
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            beatmapset  
string 
  
                
    


The beatmapset.

        

    




                    
GET api/v2/blocks




            requires user
    
            OAuth
            lazer
    






Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/blocks" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/blocks"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





    



Request

    

        GET
        /blocks
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

    




                    
POST api/v2/blocks




            requires user
    
            OAuth
            lazer
    






Example request:





    
curl --request POST \
    "https://osu.ppy.sh/api/v2/blocks" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/blocks"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());









Request

    

        POST
        /blocks
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

    




                    
DELETE api/v2/blocks/{block}




            requires user
    
            OAuth
            lazer
    






Example request:





    
curl --request DELETE \
    "https://osu.ppy.sh/api/v2/blocks/totam" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/blocks/totam"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());









Request

    

        DELETE
        /blocks/{block}
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            block  
string 
  
                
    


The block.

        

    




                    
GET api/v2/chat/presence




            requires user
    
            OAuth
            lazer
    






Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/chat/presence" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/chat/presence"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





    



Request

    

        GET
        /chat/presence
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

    




                    
POST api/v2/reports




            requires user
    
            OAuth
            lazer
    






Example request:





    
curl --request POST \
    "https://osu.ppy.sh/api/v2/reports" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/reports"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());









Request

    

        POST
        /reports
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

    




                    
PUT api/v2/rooms/{room}/users/{user}




            requires user
    
            OAuth
            lazer
    






Example request:





    
curl --request PUT \
    "https://osu.ppy.sh/api/v2/rooms/et/users/est" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/rooms/et/users/est"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "PUT",
    headers,
}).then(response => response.json());









Request

    

        PUT
        /rooms/{room}/users/{user}
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            room  
string 
  
                
    


The room.

        

            

            user  
string 
  
                
    


The user.

        

    




                    
DELETE api/v2/rooms/{room}/users/{user}




            requires user
    
            OAuth
            lazer
    






Example request:





    
curl --request DELETE \
    "https://osu.ppy.sh/api/v2/rooms/aut/users/impedit" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/rooms/aut/users/impedit"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());









Request

    

        DELETE
        /rooms/{room}/users/{user}
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            room  
string 
  
                
    


The room.

        

            

            user  
string 
  
                
    


The user.

        

    




                    
GET api/v2/rooms/{room}/leaderboard




            requires user
    
            OAuth
            public
    






Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/rooms/voluptatem/leaderboard" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/rooms/voluptatem/leaderboard"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





    



Request

    

        GET
        /rooms/{room}/leaderboard
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            room  
string 
  
                
    


The room.

        

    




                    
POST api/v2/rooms/{room}/playlist/{playlist}/scores




            requires user
    
            OAuth
            lazer
    






Example request:





    
curl --request POST \
    "https://osu.ppy.sh/api/v2/rooms/nemo/playlist/dolores/scores" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/rooms/nemo/playlist/dolores/scores"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());









Request

    

        POST
        /rooms/{room}/playlist/{playlist}/scores
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            room  
string 
  
                
    


The room.

        

            

            playlist  
string 
  
                
    


The playlist.

        

    




                    
PUT api/v2/rooms/{room}/playlist/{playlist}/scores/{score}




            requires user
    
            OAuth
            lazer
    






Example request:





    
curl --request PUT \
    "https://osu.ppy.sh/api/v2/rooms/dolorum/playlist/quis/scores/quaerat" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/rooms/dolorum/playlist/quis/scores/quaerat"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "PUT",
    headers,
}).then(response => response.json());









Request

    

        PUT
        /rooms/{room}/playlist/{playlist}/scores/{score}
    

    

        PATCH
        /rooms/{room}/playlist/{playlist}/scores/{score}
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            room  
string 
  
                
    


The room.

        

            

            playlist  
string 
  
                
    


The playlist.

        

            

            score  
string 
  
                
    


The score.

        

    




                    
POST api/v2/rooms




            requires user
    
            OAuth
            lazer
    






Example request:





    
curl --request POST \
    "https://osu.ppy.sh/api/v2/rooms" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/rooms"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());









Request

    

        POST
        /rooms
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

    




                    
GET api/v2/rooms/{room}




    
            OAuth
            public
    






Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/rooms/aut" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/rooms/aut"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





    



Request

    

        GET
        /rooms/{room}
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            room  
string 
  
                
    


The room.

        

    




                    
DELETE api/v2/rooms/{room}




            requires user
    
            OAuth
            lazer
    






Example request:





    
curl --request DELETE \
    "https://osu.ppy.sh/api/v2/rooms/ex" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/rooms/ex"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());









Request

    

        DELETE
        /rooms/{room}
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            room  
string 
  
                
    


The room.

        

    




                    
GET api/v2/seasonal-backgrounds




    
    






Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/seasonal-backgrounds" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/seasonal-backgrounds"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





    



Request

    

        GET
        /seasonal-backgrounds
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

    




                    
GET api/v2/scores/{score}/download




    
            OAuth
            public
    






Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/scores/in/download" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/scores/in/download"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





    



Request

    

        GET
        /scores/{score}/download
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            score  
string 
  
                
    


The score.

        

    




                    
GET api/v2/scores/{rulesetOrScore}/{score}/download




    
            OAuth
            public
    






Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/scores/doloribus/nihil/download" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/scores/doloribus/nihil/download"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





    



Request

    

        GET
        /scores/{rulesetOrScore}/{score}/download
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            rulesetOrScore  
string 
  
                
    


        

            

            score  
string 
  
                
    


        

    




                    
GET api/v2/scores/{rulesetOrScore}/{score?}




    
            OAuth
            public
    






Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/scores/et/voluptate" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/scores/et/voluptate"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





    



Request

    

        GET
        /scores/{rulesetOrScore}/{score?}
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            rulesetOrScore  
string 
  
                
    


        

            

            score  
string 
optional  
                
    


        

    




                    
GET api/v2/friends




            requires user
    
            OAuth
            friends.read
    






Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/friends" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/friends"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





    



Request

    

        GET
        /friends
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

    




                    
POST api/v2/friends




            requires user
    
            OAuth
            lazer
    






Example request:





    
curl --request POST \
    "https://osu.ppy.sh/api/v2/friends" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/friends"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());









Request

    

        POST
        /friends
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

    




                    
DELETE api/v2/friends/{friend}




            requires user
    
            OAuth
            lazer
    






Example request:





    
curl --request DELETE \
    "https://osu.ppy.sh/api/v2/friends/incidunt" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/friends/incidunt"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());









Request

    

        DELETE
        /friends/{friend}
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            friend  
string 
  
                
    


The friend.

        

    




                    
GET api/v2/me/download-quota-check




            requires user
    
            OAuth
            lazer
    






Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/me/download-quota-check" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/me/download-quota-check"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





    



Request

    

        GET
        /me/download-quota-check
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

    




                    
GET api/v2/users/lookup




    
            OAuth
            public
    






Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/users/lookup" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/users/lookup"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





    



Request

    

        GET
        /users/lookup
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

    




                
Users


    

                                
Get Own Data




            requires user
    
            OAuth
            identify
    



Similar to Get User but with authenticated user (token owner) as user id.




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/me/osu" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/me/osu"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





            

            
Example response (200):

        

                
"See User object section"
 

    



Request

    

        GET
        /me/{mode?}
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            mode  
string 
optional  
                
    


Ruleset. User default mode will be used if not specified.

        

    




Response format


See Get User.


session_verified attribute is included.
Additionally, statistics_rulesets is included, containing statistics for all rulesets.

                    
Get User Kudosu




    
            OAuth
            public
    



Returns kudosu history.




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/users/1/kudosu?limit=20&offset=1" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/users/1/kudosu"
);

const params = {
    "limit": "20",
    "offset": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





            

            
Example response (200):

        

                
[
    {
        "id": 1,
        "other": "attributes..."
    },
    {
        "id": 2,
        "other": "attributes..."
    }
]
 

    



Request

    

        GET
        /users/{user}/kudosu
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            user  
integer 
  
                
    


Id of the user.

        

        
Query Parameters

                    

            limit  
integer 
optional  
                
    


Maximum number of results.

        

                    

            offset  
string 
optional  
                
    


Result offset for pagination.

        

    




Response format


Array of KudosuHistory.

                    
Get User Scores




    
            OAuth
            public
    



This endpoint returns the scores of specified user.




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/users/1/scores/best?legacy_only=0&include_fails=0&mode=osu&limit=19&offset=1" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/users/1/scores/best"
);

const params = {
    "legacy_only": "0",
    "include_fails": "0",
    "mode": "osu",
    "limit": "19",
    "offset": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





            

            
Example response (200):

        

                
[
    {
        "id": 1,
        "other": "attributes..."
    },
    {
        "id": 2,
        "other": "attributes..."
    }
]
 

    



Request

    

        GET
        /users/{user}/scores/{type}
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            user  
integer 
  
                
    


Id of the user.

        

            

            type  
string 
  
                
    


Score type. Must be one of these: best, firsts, recent.

        

        
Query Parameters

                    

            legacy_only  
integer 
optional  
                
    


Whether or not to exclude lazer scores. Defaults to 0.

        

                    

            include_fails  
string 
optional  
                
    


Only for recent scores, include scores of failed plays. Set to 1 to include them. Defaults to 0.

        

                    

            mode  
string 
optional  
                
    


Ruleset of the scores to be returned. Defaults to the specified user's mode.

        

                    

            limit  
integer 
optional  
                
    


Maximum number of results.

        

                    

            offset  
string 
optional  
                
    


Result offset for pagination.

        

    




Response format


Array of Score.
Following attributes are included in the response object when applicable.






Attribute
Notes






beatmap





beatmapset





weight
Only for type best.





                    
Get User Beatmaps




    
            OAuth
            public
    



Returns the beatmaps of specified user.






Type
Notes






favourite





graveyard





guest





loved





most_played





nominated





pending
Previously unranked




ranked
Previously ranked_and_approved








Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/users/1/beatmapsets/favourite?limit=19&offset=1" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/users/1/beatmapsets/favourite"
);

const params = {
    "limit": "19",
    "offset": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





            

            
Example response (200):

        

                
[
    {
        "id": 1,
        "other": "attributes..."
    },
    {
        "id": 2,
        "other": "attributes..."
    }
]
 

    



Request

    

        GET
        /users/{user}/beatmapsets/{type}
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            user  
integer 
  
                
    


Id of the user.

        

            

            type  
string 
  
                
    


Beatmap type.

        

        
Query Parameters

                    

            limit  
integer 
optional  
                
    


Maximum number of results.

        

                    

            offset  
string 
optional  
                
    


Result offset for pagination.

        

    




Response format


Array of BeatmapPlaycount when type is most_played;
array of BeatmapsetExtended, otherwise.

                    
Get User Recent Activity




    
            OAuth
            public
    



Returns recent activity.




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/users/1/recent_activity?limit=3&offset=1" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/users/1/recent_activity"
);

const params = {
    "limit": "3",
    "offset": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





            

            
Example response (200):

        

                
[
    {
        "id": 1,
        "other": "attributes..."
    },
    {
        "id": 2,
        "other": "attributes..."
    }
]
 

    



Request

    

        GET
        /users/{user}/recent_activity
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            user  
integer 
  
                
    


Id of the user.

        

        
Query Parameters

                    

            limit  
integer 
optional  
                
    


Maximum number of results.

        

                    

            offset  
string 
optional  
                
    


Result offset for pagination.

        

    




Response format


Array of Event.

                    
Get User




    
            OAuth
            public
    



This endpoint returns the detail of specified user.





Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/users/1/osu?key=est" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/users/1/osu"
);

const params = {
    "key": "est",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





            

            
Example response (200):

        

                
"See User object section"
 

    



Request

    

        GET
        /users/{user}/{mode?}
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            user  
integer 
  
                
    


Id or @-prefixed username of the user. Previous usernames are also checked in some cases.

        

            

            mode  
string 
optional  
                
    


Ruleset. User default mode will be used if not specified.

        

        
Query Parameters

                    

            key  
string 
optional  
                
    


Type of user passed in url parameter. Can be either id or username to limit lookup by their respective type. Passing empty or invalid value will result in id lookup followed by username lookup if not found. This parameter has been deprecated. Prefix user parameter with @ instead to lookup by username.

        

    




Response format


Returns UserExtended object.
The following optional attributes on User are included:


                    
Get Users




    
            OAuth
            public
    



Returns list of users.




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/users?ids%5B%5D=1" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/users"
);

const params = {
    "ids[]": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





            

            
Example response (200):

        

                
{
    "users": [
        {
            "id": 1,
            "other": "attributes..."
        },
        {
            "id": 2,
            "other": "attributes..."
        }
    ]
}
 

    



Request

    

        GET
        /users
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
Query Parameters

                    

            ids[]  
string 
optional  
                
    


User id to be returned. Specify once for each user id requested. Up to 50 users can be requested at once.

        

                    

            include_variant_statistics  
boolean 
optional  
                
        
    


Whether to additionally include statistics_rulesets.variants (default: false).

        

    




Response format






Field
Type
Description






users
User[]
Includes country, cover, groups, and statistics_rulesets.





                
Wiki


    

                                
Get Wiki Page




    
    



The wiki article or image data.




Example request:





    
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/wiki/en/Welcome" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"





    
const url = new URL(
    "https://osu.ppy.sh/api/v2/wiki/en/Welcome"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());





    



Request

    

        GET
        /wiki/{locale}/{path}
    



    
Headers

                    

            Content-Type  
 
  
                
    


Example: application/json

        

                    

            Accept  
 
  
                
    


Example: application/json

        

        
URL Parameters

            

            locale  
string 
  
                
    


Two-letter language code of the wiki page.

        

            

            path  
string 
  
                
    


The path name of the wiki page.

        

    




Response Format


Returns WikiPage.

            

                    
Using Chat


TODO: better title


Chat consists of HTTP-based and websocket-based APIs.


The Chat websocket API allows receiving updates in real-time; this requires a connection to the Notification Websocket.
Sending messages is still performed through the HTTP-based API.



To begin receiving chat messages, clients should send the chat.start event across the socket connection.
To stop receiving chat messages, send chat.end.


Public channels and activity timeout


To continue receiving chat messages in PUBLIC channels,
clients must peridiocally request the Chat Keepalive endpoint to remain active;
30 seconds is a reasonable interval.
When a client is no longer considered active, the server will stop sending messages in public channels to the client.


Private messages are not affected by this activity timeout.


Getting the user's channel list


TODO: update default parameter


To get the list of channels the user is in, make a request to Get Updates with the presence as part of the includes parameter.
e.g. GET /chat/updates?includes[]=presence


Creating a channel


Make a request to the Create Channel endpoint.


Only PM and ANNOUNCE type channels may be created. Creating a channel will automatically join it.
Re-creating a PM channel will simply rejoin the existing channel.


Joining a channel


Make a request to the Join Channel endpoint where channel is the channel_id.


A chat.channel.join event is sent over the websocket when the user joins a channel.


Leaving a channel


Make a request to the Leave Channel endpoint.


Leaving a channel will remove it from the User's channel list.


A chat.channel.part event is sent over the websocket when the user leaves a channel.


Sending messages


Channels should be joined or created before messages are sent to them.
To send a message to a channel, make a request to the Send Message to Channel endpoint.


A chat.message.new event is sent over the websocket when the user receives a message.


Getting info about a channel


Make a request to the Get Channel endpoint.


Getting channel message history


Make a request to the Get Channel Messages endpoint.

                    
Websocket


Connection


wscat -c "{notification_endpoint}"
  -H "Authorization: Bearer {{token}}"


// Requires nodejs with using ESM.
// Browser WebSocket does not support header option.
import WebSocket from 'ws';

const url = 'notification-endpoint';
const token = 'some-token';
const headers = { Authorization: `Bearer ${token}`};

const ws = new WebSocket(url, [], { headers });
ws.on('message', (buffer) => console.log(buffer.toString()));




The above command will wait and display new notifications as they arrive




This endpoint allows you to receive notifications and chat events without constantly polling the server.


See Websocket Events for the structure of websocket messages.

                    
Websocket Events


Websocket events generally have the following standard format:


{
  "data": {},
  "event": "some.event"
}






Field
Type
Description






event
string
Name of the event.




data
object?
Event payload.






logout event


User session using same authentication key has been logged out (not yet implemented for OAuth authentication).
Server will disconnect session after sending this event so don't try to reconnect.


new event


Sent when a new notification is received.


Payload Format


See Notification object for notification types.


read event


Sent when a notification has been read.



TODO: ids should be moved to data to match other events.






Field
Type
Description






event
string
read




ids
integer[]
id of Notifications which are read






chat.channel.join


Broadcast to the user when the user joins a chat channel.


Payload Format


ChatChannel with current_user_attributes, last_message_id, users additional attributes.


chat.channel.part


Broadcast to the user when the user leaves a chat channel.


Payload Format


ChatChannel with current_user_attributes, last_message_id, users additional attributes.


chat.message.new


Sent to the user when the user receives a chat message.


Payload Format






Field
Type
Description






messages
ChatMessage[]
The messages received.




users
User[]
The related users who sent the messages.






Messages intented for a user are always sent even if the user does not currently have the channel open.
Such messages include PM and Announcement messages.


Other messages, e.g. public channel messages are not sent if the user is no longer present in the channel.

                    
Websocket Commands


Websocket commands have the format:


{
  "event": "some.event"
}






Field
Type
Description






event
string
Name of the event.






Commands currently do not have any payload.


chat.start


Send to the websocket to start receiving chat messages.


webSocket.send(JSON.stringify({ event: 'chat.start' }));


chat.end


Send to the websocket to stop receiving chat messages.


webSocket.send(JSON.stringify({ event: 'chat.end' }));

                    
Object Structures

                    
Beatmap


Represent a beatmap.






Field
Type
Description






beatmapset_id
integer





difficulty_rating
float





id
integer





mode
Ruleset





status
string
See Rank status for list of possible values.




total_length
integer





user_id
integer





version
string







Optional attributes:






Field
Type
Description






beatmapset
Beatmapset|BeatmapsetExtended|null
Beatmapset for Beatmap object, BeatmapsetExtended for BeatmapExtended object. null if the beatmap doesn't have associated beatmapset (e.g. deleted).




checksum
string?





failtimes
Failtimes





max_combo
integer









Failtimes


All fields are optional but there's always at least one field returned.






Field
Type
Description






exit
integer[]?
Array of length 100.




fail
integer[]?
Array of length 100.





                    
BeatmapDifficultyAttributes


Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.






Field
Type






max_combo
integer




star_rating
float






osu






Field
Type






aim_difficulty
float




approach_rate
float




flashlight_difficulty
float




overall_difficulty
float




slider_factor
float




speed_difficulty
float






taiko






Field
Type






stamina_difficulty
float




rhythm_difficulty
float




colour_difficulty
float




approach_rate
float




great_hit_window
float






fruits






Field
Type






approach_rate
float






mania






Field
Type






great_hit_window
float




score_multiplier
float





                    
BeatmapExtended


Represent a beatmap. This extends Beatmap with additional attributes.


Additional attributes:






Field
Type
Description






accuracy
float





ar
float





beatmapset_id
integer





bpm
float?





convert
boolean





count_circles
integer





count_sliders
integer





count_spinners
integer





cs
float





deleted_at
Timestamp?





drain
float





hit_length
integer





is_scoreable
boolean





last_updated
Timestamp





mode_int
integer





passcount
integer





playcount
integer





ranked
integer
See Rank status for list of possible values.




url
string






                    
BeatmapPack


Represent a beatmap pack.






Field
Type
Description






author
string




date
Timestamp




name
string




no_diff_reduction
boolean
Whether difficulty reduction mods may be used to clear the pack.




ruleset_id
integer




tag
string
The tag of the beatmap pack. Starts with a character representing the type (See the Tag column of BeatmapPackType) followed by an integer.




url
string
The download url of the beatmap pack.






Optional Attributes






Field
Type
Description






beatmapsets
Beatmapset[]




user_completion_data.beatmapset_ids
integer[]
IDs of beatmapsets completed by the user (according to the requirements of the pack)




user_completion_data.completed
boolean
Whether all beatmapsets are completed or not





                    
BeatmapPackType


Available beatmap pack types:






Name
Tag
Description






standard
S
Standard




featured
F
Featured Artist




tournament
P
Tournament




loved
L
Project Loved




chart
R
Spotlights




theme
T
Theme




artist
A
Artist/Album





                    
BeatmapPlaycount


Represent the playcount of a beatmap.






Field
Type
Description






beatmap_id
integer





beatmap
Beatmap?





beatmapset
Beatmapset?





count
integer






                    
BeatmapScores


{
  "scores": [],
  "userScore": {}
}






Field
Type
Description






scores
Score[]
The list of top scores for the beatmap in descending order.




userScore
BeatmapUserScore?
The score of the current user. This is not returned if the current user does not have a score. Note: will be moved to user_score in the future





                    
BeatmapUserScore


{
  "position": 1,
  "score": {}
}






Field
Type
Description






position
integer
The position of the score within the requested beatmap ranking.




score
Score
The details of the score.





                    
Beatmapset


Represents a beatmapset.






Field
Type
Description






artist
string





artist_unicode
string





covers
Covers





creator
string





favourite_count
integer





id
integer





nsfw
boolean





offset
integer





play_count
integer





preview_url
string





source
string





status
string





spotlight
boolean





title
string





title_unicode
string





user_id
integer





video
boolean







Those fields are optional.






Field
Type
Description






beatmaps
(Beatmap|BeatmapExtended)[]





converts






current_nominations
Nomination[]





current_user_attributes






description






discussions






events






genre






has_favourited
boolean





language






nominations






pack_tags
string[]





ratings






recent_favourites






related_users






user






track_id
integer









Covers






Field
Type






cover
string




cover@2x
string




card
string




card@2x
string




list
string




list@2x
string




slimcover
string




slimcover@2x
string








Rank status


The possible values are denoted either as integer or string.






Integer
String






-2
graveyard




-1
wip




0
pending




1
ranked




2
approved




3
qualified




4
loved





                    
BeatmapsetDiscussion


Represents a Beatmapset modding discussion.






Field
Type
Description






beatmap
Beatmap?





beatmap_id
integer?





beatmapset
Beatmapset?





beatmapset_id
integer





can_be_resolved
boolean





can_grant_kudosu
boolean





created_at
Timestamp





current_user_attributes
CurrentUserAttributes





deleted_at
Timestamp?





deleted_by_id
integer?





id
integer





kudosu_denied
boolean





last_post_at
Timestamp





message_type
MessageType





parent_id
integer?





posts
BeatmapsetDiscussionPost[]?





resolved
boolean





starting_post
BeatmapsetDiscussionPost?





timestamp
integer?





updated_at
Timestamp





user_id
integer







MessageType






Name
Description






hype





mapper_note





praise





problem





review





suggestion






                    
BeatmapsetDiscussionPost


Represents a post in a BeatmapsetDiscussion.






Field
Type
Description






beatmapset_discussion_id
integer





created_at
Timestamp





deleted_at
Timestamp?





deleted_by_id
integer?





id
integer





last_editor_id
integer?





message
string





system
boolean





updated_at
Timestamp





user_id
integer






                    
BeatmapsetDiscussionVote


Represents a vote on a BeatmapsetDiscussion.






Field
Type
Description






beatmapset_discussion_id
integer





created_at
Timestamp





id
integer





score
integer





updated_at
Timestamp





user_id
integer






                    
BeatmapsetExtended


Represents a beatmapset. This extends Beatmapset with additional attributes.






Field
Type
Description






availability.download_disabled
boolean





availability.more_information
string?





bpm
float





can_be_hyped
boolean





deleted_at
Timestamp?





discussion_enabled
boolean
Deprecated, all beatmapsets now have discussion enabled.




discussion_locked
boolean





hype.current
integer





hype.required
integer





is_scoreable
boolean





last_updated
Timestamp





legacy_thread_url
string?





nominations_summary.current
integer





nominations_summary.required
integer





ranked
integer
See Rank status for list of possible values.




ranked_date
Timestamp?





source
string





storyboard
boolean





submitted_date
Timestamp?





tags
string







The following attributes are always included as well:






Field






has_favourited





                    
Build


{
  "id": 5778,
  "version": "20210520.2",
  "display_version": "20210520.2",
  "users": 22059,
  "created_at": "2021-05-20T14:28:04+00:00",
  "update_stream": {
    "id": 5,
    "name": "stable40",
    "display_name": "Stable",
    "is_featured": true
  }
}






Field
Type






created_at
Timestamp




display_version
string




id
integer




update_stream
UpdateStream?




users
integer




version
string?




youtube_id
string?






Optional Attributes


The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.






Field
Type
Notes






changelog_entries
ChangelogEntry[]
If the build has no changelog entries, a placeholder is generated.




versions
Versions









Versions






Field
Type






next
Build?




previous
Build?





                    
ChangelogEntry


{
  "id": null,
  "repository": null,
  "github_pull_request_id": null,
  "github_url": null,
  "url": "https://osu.ppy.sh/home/news/2021-05-20-spring-fanart-contest-results",
  "type": "fix",
  "category": "Misc",
  "title": "Spring is here!",
  "message_html": "<div class='changelog-md'><p class=\"changelog-md__paragraph\">New seasonal backgrounds ahoy! Amazing work by the artists.</p>\n</div>",
  "major": true,
  "created_at": "2021-05-20T10:56:49+00:00"
}






Field
Type






category
string




created_at
Timestamp?




github_pull_request_id
integer?




github_url
string?




id
integer?




major
boolean




repository
string?




title
string?




type
string




url
string?






Optional Attributes


The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.






Field
Type
Notes






github_user
GithubUser
If the changelog entry has no GitHub user, a placeholder is generated.




message
string?
Entry message in Markdown format. Embedded HTML is allowed.




message_html
string?
Entry message in HTML format.





                    
ChatChannel


{
  "channel_id": 1337,
  "current_user_attributes": {
    "can_message": true,
    "can_message_error": null,
    "last_read_id": 9150005005,
  },
  "name": "test channel",
  "description": "wheeeee",
  "icon": "/images/layout/avatar-guest@2x.png",
  "type": "GROUP",
  "last_read_id": 9150005005,
  "last_message_id": 9150005005,
  "moderated": false,
  "users": [
    2,
    3,
    102
  ]
}


Represents an individual chat "channel" in the game.






Field
Type
Description






channel_id
integer





name
string





description
string?





icon
string?
display icon for the channel




type
ChannelType
type of channel




message_length_limit
integer





moderated
boolean
user can't send message when the value is true




uuid
string?
value from requests that is relayed back to the sender.






Optional attributes:






Field
Type
Description






current_user_attributes
CurrentUserAttributes?
only present on some responses




last_read_id
integer?
Deprecated; use current_user_attributes.last_read_id.




last_message_id
integer?
message_id of last known message (only returned in presence responses)




recent_messages
ChatMessage[]?
Deprecated; up to 50 most recent messages




users
integer[]?
array of user_id that are in the channel (not included for PUBLIC channels)





                    
ChannelType






Type
Permission Check for Joining/Messaging






PUBLIC





PRIVATE
is player in the allowed groups? (channel.allowed_groups)




MULTIPLAYER
is player currently in the mp game?




SPECTATOR





TEMPORARY
deprecated




PM
see below (user_channels)




GROUP
is player in channel? (user_channels)




ANNOUNCE
is user in the announce group?






For PMs, two factors are taken into account:



                    
ChatMessage


{
  "channel_id": 5,
  "content": "i am a lazerface",
  "is_action": false,
  "message_id": 9150005004,
  "sender_id": 2,
  "timestamp": "2018-07-06T06:33:34+00:00",
  "type": "plain",
  "uuid": "some-uuid-string",
  "sender": {
    "id": 2,
    "username": "peppy",
    "profile_colour": "#3366FF",
    "avatar_url": "https://a.ppy.sh/2?1519081077.png",
    "country_code": "AU",
    "is_active": true,
    "is_bot": false,
    "is_online": true,
    "is_supporter": true
  }
}


Represents an individual Message within a ChatChannel.






Field
Type
Description






channel_id
integer
channel_id of where the message was sent




content
string
message content




is_action
boolean
was this an action? i.e. /me dances




message_id
integer
unique identifier for message




sender_id
integer
user_id of the sender




timestamp
Timestamp
when the message was sent, ISO-8601




type
string
type of message; 'action', 'markdown' or 'plain'




uuid
string?
message identifier originally sent by client






Optional attributes:






Field
Type
Description






sender
User
embedded User object to save additional api lookups





                    
Comment


{
  "commentable_id": 407,
  "commentable_type": "news_post",
  "created_at": "2019-09-05T06:31:20+00:00",
  "deleted_at": null,
  "edited_at": null,
  "edited_by_id": null,
  "id": 276,
  "legacy_name": null,
  "message": "yes",
  "message_html": "<div class='osu-md-default'><p class=\"osu-md-default__paragraph\">yes</p>\n</div>",
  "parent_id": null,
  "pinned": true,
  "replies_count": 0,
  "updated_at": "2019-09-05T06:31:20+00:00",
  "user_id": 1,
  "votes_count": 0
}


Represents a single comment.






Field
Type
Description






commentable_id
integer
ID of the object the comment is attached to




commentable_type
string
type of object the comment is attached to




created_at
Timestamp
ISO 8601 date




deleted_at
Timestamp?
ISO 8601 date if the comment was deleted; null, otherwise




edited_at
Timestamp?
ISO 8601 date if the comment was edited; null, otherwise




edited_by_id
integer?
user id of the user that edited the post; null, otherwise




id
integer
the ID of the comment




legacy_name
string?
username displayed on legacy comments




message
string?
markdown of the comment's content




message_html
string?
html version of the comment's content




parent_id
integer?
ID of the comment's parent




pinned
boolean
Pin status of the comment




replies_count
integer
Number of replies to the comment




updated_at
Timestamp
ISO 8601 date




user_id
integer
user ID of the poster




votes_count
integer
Number of votes





                    
CommentBundle


{
  "commentable_meta": [
    {
      "id": 407,
      "title": "Clicking circles linked to increased performance",
      "type": "news_post",
      "url": "https://osu.ppy.sh/home"
    }
  ],
  "comments": [
    {
      "commentable_id": 407,
      "commentable_type": "news_post",
      "created_at": "2019-09-05T06:31:20+00:00",
      "deleted_at": null,
      "edited_at": null,
      "edited_by_id": null,
      "id": 276,
      "legacy_name": null,
      "message": "yes",
      "message_html": "<div class='osu-md-default'><p class=\"osu-md-default__paragraph\">yes</p>\n</div>",
      "parent_id": null,
      "replies_count": 0,
      "updated_at": "2019-09-05T06:31:20+00:00",
      "user_id": 1,
      "votes_count": 1337
    },
    {
      "commentable_id": 407,
      "commentable_type": "news_post",
      "created_at": "2019-09-05T07:31:20+00:00",
      "deleted_at": null,
      "edited_at": null,
      "edited_by_id": null,
      "id": 277,
      "legacy_name": null,
      "message": "absolutely",
      "message_html": "<div class='osu-md-default'><p class=\"osu-md-default__paragraph\">absolutely</p>\n</div>",
      "parent_id": null,
      "replies_count": 0,
      "updated_at": "2019-09-05T07:31:20+00:00",
      "user_id": 2,
      "votes_count": 1337
    }
  ],
  "has_more": true,
  "has_more_id": 276,
  "included_comments": [],
  "pinned_comments": [],
  "sort": "new",
  "user_follow": false,
  "user_votes": [277],
  "users": [
    {
      "avatar_url": "https://a.ppy.sh/2?1519081077.png",
      "country_code": "AU",
      "default_group": "pippi",
      "id": 1,
      "is_active": true,
      "is_bot": false,
      "is_online": true,
      "is_supporter": true,
      "last_visit": "2025-09-05T08:35:00+00:00",
      "pm_friends_only": false,
      "profile_colour": null,
      "username": "pippi"
    },
    {
      "avatar_url": "https://a.ppy.sh/2?1519081077.png",
      "country_code": "AU",
      "default_group": "yuzu",
      "id": 2,
      "is_active": true,
      "is_bot": false,
      "is_online": false,
      "is_supporter": true,
      "last_visit": "2025-09-04T09:28:00+00:00",
      "pm_friends_only": false,
      "profile_colour": null,
      "username": "yuzu"
     }
  ]
}


Comments and related data.






Field
Type
Description






commentable_meta
CommentableMeta[]
ID of the object the comment is attached to




comments
Comment[]
Array of comments ordered according to sort;




cursor
Cursor




has_more
boolean
If there are more comments or replies available




has_more_id
integer?




included_comments
Comment[]
Related comments; e.g. parent comments and nested replies




pinned_comments
Comment[]?
Pinned comments




sort
string
one of the CommentSort types




top_level_count
integer?
Number of comments at the top level. Not returned for replies.




total
integer?
Total number of comments. Not retuned for replies.




user_follow
boolean
is the current user watching the comment thread?




user_votes
integer[]
IDs of the comments in the bundle the current user has upvoted




users
User[]
array of users related to the comments





                    
CommentSort


Available sort types are new, old, top.






Type
Sort Fields






new
created_at (descending), id (descending)




old
created_at (ascending), id (ascending)




top
votes_count (descending), created_at (descending), id (descending)






Building cursor for comments listing


The returned response will be for comments after the specified sort fields.


For example, use last loaded comment for the fields value to load more comments. Also make sure to use same sort and parent_id values.

                    
CommentableMeta


{
  "id": 407,
  "title": "Clicking circles linked to increased performance",
  "type": "news_post",
  "url": "https://osu.ppy.sh/home/"
}


Metadata of the object that a comment is attached to.


If object is available:






Field
Type
Description






current_user_attributes
CurrentUserAttributes





id
integer
the ID of the object




owner_id
integer?
User ID which owns the object




owner_title
string?
Object owner type, used for display (MAPPER for beatmapset)




title
string
display title




type
string
the type of the object




url
string
url of the object






Otherwise if object has been deleted:






Field
Type
Description






title
string
display title








CurrentUserAttributes






Field
Type
Description






can_new_comment_reason
string?
null if current user can comment on it, reason sentence otherwise





                    
CurrentUserAttributes


An object listing various related permissions and states for the current user, related to the object it is attached to.


BeatmapsetDiscussionPermissions


TODO: needs a better name.






Name
Description






can_destroy
Can delete the discussion.




can_reopen
Can reopen the discussion.




can_moderate_kudosu
Can allow or deny kudosu.




can_resolve
Can resolve the discussion.




vote_score
Current vote given to the discussion.






ChatChannelUserAttributes






Name
Type
Description






can_message
boolean
Can send messages to this channel.




can_message_error
string?
Reason messages cannot be sent to this channel




last_read_id
integer
message_id of last message read.





                    
Cursor


{
  "_id": 5,
  "_score": 36.234
}
// query string: cursor[_id]=5&cursor[_score]=36.234


{
  "page": 2,
}
// query string: cursor[page]=2


A structure included in some API responses containing the parameters to get the next set of results.


The values of the cursor should be provided to next request of the same endpoint to get the next set of results.


If there are no more results available, a cursor with a value of null is returned: "cursor": null.


Note that sort option should also be specified for it to work.


                    
CursorString


A string value included in some API responses containing the parameter to get the next set of results.


Its value will be null (or not defined) if there are no more results available.


Note that all parameters used in previous request also need to be passed.

                    
Event


The object has different attributes depending on its type. Following are attributes available to all types.






Field
Type
Description






created_at
Timestamp





id
integer





type
Event.Type







Additional objects




Beatmap






Field
Type






title
string




url
string








Beatmapset






Field
Type






title
string




url
string








User






Field
Type
Description






username
string





url
string





previousUsername
string?
Only for usernameChange event.








Available Types


achievement


When user obtained an achievement.






Field
Type






achievement
Achievement




user
Event.User






beatmapPlaycount


When a beatmap has been played for certain number of times.






Field
Type






beatmap
Event.Beatmap




count
integer






beatmapsetApprove


When a beatmapset changes state.






Field
Type
Description






approval
string
ranked, approved, qualified, loved.




beatmapset
Event.Beatmapset





user
Event.User
Beatmapset owner.






beatmapsetDelete


When a beatmapset is deleted.






Field
Type






beatmapset
Event.Beatmapset






beatmapsetRevive


When a beatmapset in graveyard state is updated.






Field
Type
Description






beatmapset
Event.Beatmapset





user
Event.User
Beatmapset owner.






beatmapsetUpdate


When a beatmapset is updated.






Field
Type
Description






beatmapset
Event.Beatmapset





user
Event.User
Beatmapset owner.






beatmapsetUpload


When a new beatmapset is uploaded.






Field
Type
Description






beatmapset
Event.Beatmapset





user
Event.User
Beatmapset owner.






rank


When a user achieves a certain rank on a beatmap.






Field
Type
Description






scoreRank
string
(FIXME)




rank
integer





mode
Ruleset





beatmap
Event.Beatmap





user
Event.User







rankLost


When a user loses first place to another user.






Field
Type






mode
Ruleset




beatmap
Event.Beatmap




user
Event.User






userSupportAgain


When a user supports osu! for the second and onwards.






Field
Type






user
Event.User






userSupportFirst


When a user becomes a supporter for the first time.






Field
Type






user
Event.User






userSupportGift


When a user is gifted a supporter tag by another user.






Field
Type
Description






user
Event.User
Recipient user.






usernameChange


When a user changes their username.






Field
Type
Description






user
Event.User
Includes previousUsername.





                    
Forum Post






Field
Type
Description






created_at
Timestamp





deleted_at
Timestamp?





edited_at
Timestamp?





edited_by_id
integer?





forum_id
integer





id
integer





topic_id
integer





user_id
integer







Following fields are optional.






Field
Type
Description






body.html
string
Post content in HTML format.




body.raw
string
Post content in BBCode format.





                    
Forum Topic






Field
Type






created_at
Timestamp




deleted_at
Timestamp?




first_post_id
integer




forum_id
integer




id
integer




is_locked
boolean




last_post_id
integer




poll
Poll?




post_count
integer




title
string




type
normal | sticky | announcement




updated_at
Timestamp




user_id
integer








Poll






Field
Type






allow_vote_change
boolean




ended_at
Timestamp?




hide_incomplete_results
boolean




last_vote_at
Timestamp?




max_votes
integer




options
PollOption[]




started_at
Timestamp




title.bbcode
string




title.html
string




total_vote_count
integer








PollOption






Field
Type
Notes






id
integer
Unique only per-topic.




text.bbcode
string





text.html
string





vote_count
integer?
Not present if the poll is incomplete and results are hidden.





                    
GithubUser


{
  "display_name": "bdach",
  "github_url": "https://github.com/bdach",
  "github_username": "bdach",
  "id": 218,
  "osu_username": null,
  "user_id": null,
  "user_url": null
}






Field
Type






display_name
string




github_url
string?




github_username
string?




id
integer?




osu_username
string?




user_id
integer?




user_url
string?





                    
Group


This object is not returned by any endpoints yet. It is here only as a reference for UserGroup.






Field
Type
Description






colour
string?





has_listing
boolean
Whether this group displays a listing at /groups/{id}.




has_playmodes
boolean
Whether this group associates Rulesets with users' memberships.




id
integer





identifier
string
Unique string to identify the group.




is_probationary
boolean
Whether members of this group are considered probationary.




name
string





short_name
string
Short name of the group for display.






Optional Attributes


The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.






Field
Type






description
Description?








Description






Field
Type






html
string




markdown
string





                    
KudosuHistory






Field
Type
Description






id
integer





action
string
One of give, vote.give, reset, vote.reset, revoke, or vote.revoke.




amount
integer





model
string
Object type which the exchange happened on (forum_post, etc).




created_at
Timestamp





giver
Giver?
Simple detail of the user who started the exchange.




post
Post
Simple detail of the object for display.






Giver






Field
Type






url
string




username
string






Post






Field
Type
Description






url
string?
Url of the object.




title
string
Title of the object. It'll be "[deleted beatmap]" for deleted beatmaps.





                    
Match






Field
Type
Description






id
integer





start_time
Timestamp





end_time
Timestamp?





name
string






                    
MatchEvent






Field
Type
Description






id
integer





detail.type
MatchEventType





detail.text
string





timestamp
Timestamp





user_id
integer?







Optional Attributes






Field
Type
Description






game
MatchGame
The game associated with the MatchEvent








MatchEventType






Name
Description






host-changed





match-created





match-disbanded





other





player-joined





player-kicked





player-left






                    
MatchGame






Field
Type
Description






id
integer





beatmap
Beatmap
Includes beatmapset.




beatmap_id
integer





start_time
Timestamp





end_time
Timestamp?





mode
Ruleset





mode_int
integer





mods
string[]
Mod combination used for this match game as an array of mod acronyms.




scores
Score[]
List of scores set by each player for this match game.




scoring_type
string
accuracy, combo, score, scorev2.




team_type
string
head-to-head, tag-coop, tag-team-vs, team-vs.





                    
MultiplayerScores


An object which contains scores and related data for fetching next page of the result.






Field
Type
Description






cursor_string
CursorString
To be used to fetch the next page.




params
object
Parameters used for score listing.




scores
Score[]





total
integer?
Index only. Total scores of the specified playlist item.




user_score
Score?
Index only. Score of the accessing user if exists.





                    
MultiplayerScoresAround






Field
Type
Description






higher
MultiplayerScores





lower
MultiplayerScores






                    
MultiplayerScoresCursor


An object which contains pointer for fetching further results of a request. It depends on the sort option.






Field
Type
Description






score_id
integer
Last score id of current result (score_asc, score_desc).




total_score
integer
Last score's total score of current result (score_asc, score_desc).





                    
MultiplayerScoresSort


Sort option for multiplayer scores index.






Name
Description






score_asc
Sort by scores, ascending.




score_desc
Sort by scores, descending.





                    
NewsPost






Field
Type
Description






author
string





edit_url
string
Link to the file view on GitHub.




first_image
string?
Link to the first image in the document.




first_image@2x
string?
Larger size version of first_image.




id
integer





published_at
Timestamp





slug
string
Filename without the extension, used in URLs.




title
string





updated_at
Timestamp







Optional Attributes






Field
Type
Description






content
string
HTML post content.




navigation
Navigation
Navigation metadata.




preview
string
First paragraph of content with HTML markup stripped.








Navigation






Field
Type
Description






newer
NewsPost?
Next post.




older
NewsPost?
Previous post.





                    
Nomination






Field
Type






beatmapset_id
integer




rulesets
Ruleset[]




reset
boolean




user_id
integer





                    
Notification


{
  "id": 1,
  "name": "channel_message",
  "created_at": "2019-04-24T07:12:43+00:00",
  "object_type": "channel",
  "object_id": 1,
  "source_user_id": 1,
  "is_read": true,
  "details": {
    "username": "someone",
    ...
  }
}


Represents a notification object.






Field
Type
Description






id
integer





name
string
Name of the event




created_at
Timestamp
ISO 8601 date




object_type
string





object_id
integer





source_user_id
integer?





is_read
boolean





details
object
message_id of last known message (only returned in presence responses)






Event Names






Name
Description






beatmapset_discussion_lock
Discussion on beatmap has been locked




beatmapset_discussion_post_new
New discussion post on beatmap




beatmapset_discussion_unlock
Discussion on beatmap has been unlocked




beatmapset_disqualify
Beatmap was disqualified




beatmapset_love
Beatmap was promoted to loved




beatmapset_nominate
Beatmap was nominated




beatmapset_qualify
Beatmap has gained enough nominations and entered the ranking queue




beatmapset_remove_from_loved
Beatmap was removed from Loved




beatmapset_reset_nominations
Nomination of beatmap was reset




channel_message
Someone sent chat message




forum_topic_reply
Someone replied on forum topic








beatmapset_discussion_lock






Field
Type
Description






object_id
integer
Beatmapset id




object_type
string
beatmapset




source_user_id
integer
User who locked discussion






Details object:






Field
Type
Description






cover_url
string
Beatmap cover




title
string
Beatmap title




username
string
Username of source_user_id








beatmapset_discussion_post_new






Field
Type
Description






object_id
integer
Beatmapset id




object_type
string
beatmapset




source_user_id
integer
Poster of the discussion






Details object:






Field
Type
Description






title
string
Beatmap title




cover_url
string
Beatmap cover




discussion_id
integer





post_id
integer





beatmap_id
integer?
null if posted to general all




username
string
Username of source_user_id








beatmapset_discussion_unlock






Field
Type
Description






object_id
integer
Beatmapset id




object_type
string
beatmapset




source_user_id
integer
User who unlocked discussion






Details object:






Field
Type
Description






title
string
Beatmap title




cover_url
string
Beatmap cover




username
string
Username of source_user_id








beatmapset_disqualify






Field
Type
Description






object_id
integer
Beatmapset id




object_type
string
beatmapset




source_user_id
integer
User who disqualified beatmapset






Details object:






Field
Type
Description






title
string
Beatmap title




cover_url
string
Beatmap cover




username
string
Username of source_user_id








beatmapset_love






Field
Type
Description






object_id
integer
Beatmapset id




object_type
string
beatmapset




source_user_id
integer
User who promoted beatmapset to loved






Details object:






Field
Type
Description






title
string
Beatmap title




cover_url
string
Beatmap cover




username
string
Username of source_user_id








beatmapset_nominate






Field
Type
Description






object_id
integer
Beatmapset id




object_type
string
beatmapset




source_user_id
integer
User who nominated beatmapset






Details object:






Field
Type
Description






title
string
Beatmap title




cover_url
string
Beatmap cover




username
string
Username of source_user_id








beatmapset_qualify






Field
Type
Description






object_id
integer
Beatmapset id




object_type
string
beatmapset




source_user_id
integer
User whom beatmapset nomination triggered qualification






Details object:






Field
Type
Description






title
string
Beatmap title




cover_url
string
Beatmap cover




username
string
Username of source_user_id








beatmapset_remove_from_loved






Field
Type
Description






object_id
integer
Beatmapset id




object_type
string
beatmapset




source_user_id
integer
User who removed beatmapset from Loved






Details object:






Field
Type
Description






title
string
Beatmap title




cover_url
string
Beatmap cover




username
string
Username of source_user_id








beatmapset_reset_nominations






Field
Type
Description






object_id
integer
Beatmapset id




object_type
string
beatmapset




source_user_id
integer
User who triggered nomination reset






Details object:






Field
Type
Description






title
string
Beatmap title




cover_url
string
Beatmap cover




username
string
Username of source_user_id








channel_message






Field
Type
Description






object_id
integer
Channel id




object_type
string
channel




source_user_id
integer
User who posted message






Details object:






Field
Type
Description






title
string
Up to 36 characters of the message (ends with ... when exceeding 36 characters)




cover_url
string
Avatar of source_user_id




username
string
Username of source_user_id








forum_topic_reply






Field
Type
Description






object_id
integer
Topic id




object_type
string
forum_topic




source_user_id
integer
User who posted message






Details object:






Field
Type
Description






title
string
Title of the replied topic




cover_url
string
Topic cover




post_id
integer
Post id




username
string?
Username of source_user_id





                    
RankingType


Available ranking types:






Name
Description






charts
Spotlight




country
Country




performance
Performance




score
Score





                    
Rankings


{
  "cursor": {

  },
  "ranking": [
    {
      "grade_counts": {
          "a": 3,
          "s": 2,
          "sh": 6,
          "ss": 2,
          "ssh": 3
      },
      "hit_accuracy": 92.19,
      "is_ranked": true,
      "level": {
          "current": 30,
          "progress": 0
      },
      "maximum_combo": 3948,
      "play_count": 228050,
      "play_time": null,
      "pp": 990,
      "global_rank": 87468,
      "ranked_score": 1502995536,
      "replays_watched_by_others": 0,
      "total_hits": 5856573,
      "total_score": 2104193750,
      "user": {
          "avatar_url": "/images/layout/avatar-guest.png",
          "country": {
              "code": "GF",
              "name": "French Guiana"
          },
          "country_code": "GF",
          "cover": {
              "custom_url": null,
              "id": "3",
              "url": "http://osuweb.test/images/headers/profile-covers/c3.jpg"
          },
          "default_group": "default",
          "id": 458402,
          "is_active": false,
          "is_bot": false,
          "is_online": false,
          "is_supporter": true,
          "last_visit": "2017-02-22T11:07:10+00:00",
          "pm_friends_only": false,
          "profile_colour": null,
          "username": "serdman"
      }
    }
  ],
  "total": 100
}






Field
Type
Description






beatmapsets
BeatmapsetExtended[]?
The list of beatmaps in the requested spotlight for the given mode; only available if type is charts




cursor
Cursor
A cursor




ranking
UserStatistics[]

User statistics for the requested ruleset in order of descending rank.
Includes user, user.country, and user.cover.
Includes rank_change_since_30_days if the ranking type is performance with no additional filters applied.		




spotlight
Spotlight?
Spotlight details; only available if type is charts




total
integer
An approximate count of ranks available





                    
Ruleset


Available rulesets:






Name
Description






fruits
osu!catch




mania
osu!mania




osu
osu!standard




taiko
osu!taiko





                    
Score


The following is the format returned when API v2 version header is 20220705 or higher. Exceptions apply (f.ex. doesn't apply for legacy match score).






Field
Type
Description






accuracy
float





beatmap_id
integer





best_id
integer?





build_id
integer?





classic_total_score
integer
Only for solo_score type




ended_at
Timestamp





has_replay
boolean





id
integer





is_perfect_combo
boolean





legacy_perfect
boolean





legacy_score_id
integer?





legacy_total_score
integer





max_combo
integer





maximum_statistics
ScoreStatistics





mods
Mod[]





passed
boolean





playlist_item_id
integer
Only for multiplayer score




pp
float?





preserve
boolean
Whether or not the score may eventually be deleted. Only for solo_score type




processed
boolean
Only for solo_score type




rank
string





ranked
boolean
Whether or not the score can have pp. Only for solo_score type




room_id
integer
Only for multiplayer score




ruleset_id
integer





started_at
Timestamp?





statistics
ScoreStatistics





total_score
integer





type
string





user_id
integer







Initial version


The following is the format returned when API v2 version header is 20220704 or lower.






Field
Type
Description






id






best_id






user_id






accuracy






mods






score






max_combo






perfect






statistics.count_50






statistics.count_100






statistics.count_300






statistics.count_geki






statistics.count_katu






statistics.count_miss






passed
boolean





pp






rank






created_at






mode






mode_int






replay








Optional attributes






Field
Type
Description






beatmap






beatmapset






current_user_attributes
integer?





match

Only for legacy match score




position
integer?
Only for multiplayer score




rank_country






rank_global






scores_around
MultiplayerScoresAround?
Scores around the specified score. Only for multiplayer score




user






weight







                    
Spotlight


{
  "end_date": "2019-03-22T00:00:00+00:00",
  "id": 1,
  "mode_specific": false,
  "name": "Best spinning circles 2019",
  "start_date": "2019-02-22T00:00:00+00:00",
  "type": "yearly",
}


The details of a spotlight.






Field
Type
Description






end_date
Timestamp
The end date of the spotlight.




id
integer
The ID of this spotlight.




mode_specific
boolean
If the spotlight has different mades specific to each Ruleset.




participant_count
integer?
The number of users participating in this spotlight. This is only shown when viewing a single spotlight.




name
string
The name of the spotlight.




start_date
Timestamp
The starting date of the spotlight.




type
string
The type of spotlight.





                    
Spotlights


{
  "spotlights": [
    {
      "end_date": "2019-03-22T00:00:00+00:00",
      "id": 1,
      "mode_specific": false,
      "name": "Best spinning circles 2019",
      "start_date": "2019-02-22T00:00:00+00:00",
      "type": "yearly",
    },
    {
      "end_date": "2019-03-22T00:00:00+00:00",
      "id": 2,
      "mode_specific": true,
      "name": "Ultimate fruit collector February 2019",
      "start_date": "2019-02-22T00:00:00+00:00",
      "type": "monthly",
    }
  ],
}






Field
Type
Description






spotlights
Spotlight[]
An array of spotlights





                    
Timestamp


  "2020-01-01T00:00:00+00:00"


Timestamp string in ISO 8601 format.

                    
UpdateStream


{
  "id": 7,
  "name": "lazer",
  "display_name": "Lazer",
  "is_featured": false
}






Field
Type






display_name
string?




id
integer




is_featured
boolean




name
string






Optional Attributes


The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.






Field
Type






latest_build
Build?




user_count
integer





                    
User


{
  "id": 2,
  "username": "peppy",
  "profile_colour": "#3366FF",
  "avatar_url": "https://a.ppy.sh/2?1519081077.png",
  "country_code": "AU",
  "is_active": true,
  "is_bot": false,
  "is_deleted": false,
  "is_online": true,
  "is_supporter": true
}


Represents a user.






Field
Type
Description






avatar_url
string
url of user's avatar




country_code
string
two-letter code representing user's country




default_group
string?
Identifier of the default Group the user belongs to.




id
integer
unique identifier for user




is_active
boolean
has this account been active in the last x months?




is_bot
boolean
is this a bot account?




is_deleted
boolean





is_online
boolean
is the user currently online? (either on lazer or the new website)




is_supporter
boolean
does this user have supporter?




last_visit
Timestamp?
last access time. null if the user hides online presence




pm_friends_only
boolean
whether or not the user allows PM from other than friends




profile_colour
string?
colour of username/profile highlight, hex code (e.g. #333333)




username
string
user's display name








Optional attributes


Following are attributes which may be additionally included in the response. Relevant endpoints should list them if applicable.






Field
Type
Notes






account_history
User.UserAccountHistory[]





active_tournament_banner
User.ProfileBanner?
Deprecated, use active_tournament_banners instead.




active_tournament_banners
User.ProfileBanner[]





badges
User.UserBadge[]





beatmap_playcounts_count
integer





blocks






country






cover






favourite_beatmapset_count
integer





follow_user_mapping
integer[]





follower_count
integer





friends






graveyard_beatmapset_count
integer





groups
UserGroup[]





guest_beatmapset_count
integer





is_restricted
boolean?





kudosu
User.Kudosu





loved_beatmapset_count
integer





mapping_follower_count
integer





monthly_playcounts
UserMonthlyPlaycount[]





page






pending_beatmapset_count






previous_usernames






rank_highest
User.RankHighest?





rank_history






ranked_beatmapset_count






replays_watched_counts






scores_best_count
integer





scores_first_count
integer





scores_recent_count
integer





session_verified
boolean





statistics
UserStatistics





statistics_rulesets
UserStatisticsRulesets





support_level






unread_pm_count






user_achievements






user_preferences










Kudosu






Field
Type






available
integer




total
integer








ProfileBanner






Field
Type
Description






id
integer





tournament_id
integer





image
string?





image@2x
string?









ProfilePage






Section






me




recent_activity




beatmaps




historical




kudosu




top_ranks




medals








RankHighest






Field
Type






rank
integer




updated_at
Timestamp








UserAccountHistory






Field
Type
Description






description
string?





id
integer





length
integer
In seconds.




permanent
boolean





timestamp
Timestamp





type
string
note, restriction, or silence.








UserBadge






Field
Type
Description






awarded_at
Timestamp





description
string





image@2x_url
string





image_url
string





url
string






                    
UserExtended


{
  "avatar_url": "https://a.ppy.sh/1?1501234567.jpeg",
  "country_code": "AU",
  "default_group": "default",
  "id": 1,
  "is_active": true,
  "is_bot": false,
  "is_deleted": false,
  "is_online": false,
  "is_supporter": true,
  "last_visit": "2020-01-01T00:00:00+00:00",
  "pm_friends_only": false,
  "profile_colour": "#000000",
  "username": "osuuser",
  "cover_url": "https://assets.ppy.sh/user-profile-covers/1/0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef.jpeg",
  "discord": "osuuser#1337",
  "has_supported": true,
  "interests": null,
  "join_date": "2010-01-01T00:00:00+00:00",
  "kudosu": {
    "total": 20,
    "available": 10
  },
  "location": null,
  "max_blocks": 50,
  "max_friends": 500,
  "occupation": null,
  "playmode": "osu",
  "playstyle": [
    "mouse",
    "touch"
  ],
  "post_count": 100,
  "profile_hue": 42,
  "profile_order": [
    "me",
    "recent_activity",
    "beatmaps",
    "historical",
    "kudosu",
    "top_ranks",
    "medals"
  ],
  "title": null,
  "twitter": "osuuser",
  "website": "https://osu.ppy.sh",
  "country": {
    "code": "AU",
    "name": "Australia"
  },
  "cover": {
    "custom_url": "https://assets.ppy.sh/user-profile-covers/1/0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef.jpeg",
    "url": "https://assets.ppy.sh/user-profile-covers/1/0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef.jpeg",
    "id": null
  },
  "is_restricted": false,
  "account_history": [],
  "active_tournament_banner": null,
  "badges": [
    {
      "awarded_at": "2015-01-01T00:00:00+00:00",
      "description": "Test badge",
      "image@2x_url": "https://assets.ppy.sh/profile-badges/test@2x.png",
      "image_url": "https://assets.ppy.sh/profile-badges/test.png",
      "url": ""
    }
  ],
  "favourite_beatmapset_count": 10,
  "follower_count": 100,
  "graveyard_beatmapset_count": 10,
  "groups": [
    {
      "id": 1,
      "identifier": "gmt",
      "name": "gmt",
      "short_name": "GMT",
      "description": "",
      "colour": "#FF0000"
    }
  ],
  "loved_beatmapset_count": 0,
  "monthly_playcounts": [
    {
      "start_date": "2019-11-01",
      "count": 100
    },
    {
      "start_date": "2019-12-01",
      "count": 150
    },
    {
      "start_date": "2020-01-01",
      "count": 20
    }
  ],
  "page": {
    "html": "<div class='bbcode bbcode--profile-page'><center>Hello</center></div>",
    "raw": "[centre]Hello[/centre]"
  },
  "pending_beatmapset_count": 0,
  "previous_usernames": [],
  "ranked_beatmapset_count": 10,
  "replays_watched_counts": [
    {
      "start_date": "2019-11-01",
      "count": 10
    },
    {
      "start_date": "2019-12-01",
      "count": 12
    },
    {
      "start_date": "2020-01-01",
      "count": 1
    }
  ],
  "scores_first_count": 0,
  "statistics": {
    "level": {
      "current": 60,
      "progress": 55
    },
    "pp": 100,
    "global_rank": 2000,
    "ranked_score": 2000000,
    "hit_accuracy": 90.5,
    "play_count": 1000,
    "play_time": 100000,
    "total_score": 3000000,
    "total_hits": 6000,
    "maximum_combo": 500,
    "replays_watched_by_others": 270,
    "is_ranked": true,
    "grade_counts": {
      "ss": 10,
      "ssh": 5,
      "s": 50,
      "sh": 0,
      "a": 40
    },
    "rank": {
      "global": 15000,
      "country": 30000
    }
  },
  "support_level": 3,
  "user_achievements": [
    {
      "achieved_at": "2020-01-01T00:00:00+00:00",
      "achievement_id": 1
    }
  ],
  "rank_history": {
    "mode": "osu",
    "data": [
      16200,
      15500,
      15000
    ]
  }
}


Represents a user. Extends User object with additional attributes.






Field
Type
Description






cover_url
string
url of profile cover. Deprecated, use cover.url instead.




discord
string?





has_supported
boolean
Whether or not the user has a current or past osu!supporter tag.




interests
string?





join_date
Timestamp





location
string?





max_blocks
integer
maximum number of users allowed to be blocked




max_friends
integer
maximum number of friends allowed to be added




occupation
string?





playmode
Ruleset





playstyle
string[]
Device choices of the user.




post_count
integer
Number of forum posts




profile_hue
integer?
Custom colour hue in HSL degrees (0–359).




profile_order
ProfilePage[]
ordered array of sections in user profile page




title
string?
user-specific title




title_url
string?





twitter
string?





website
string?







In addition, the following optional attributes on User are included:


                    
UserGroup


Describes a Group membership of a User. It contains all of the attributes of the Group, in addition to what is listed here.






Field
Type
Description






playmodes
string[]?
Rulesets associated with this membership (null if has_playmodes is unset).





                    
UserSilence


{
  "id": 1,
  "user_id": 5
}


A record indicating a User was silenced.






Field
Type
Description






id
integer
id of this object.




user_id
integer
id of the User that was silenced





                    
UserStatistics


{
  "count_100": 0,
  "count_300": 0,
  "count_50": 0,
  "count_miss": 0,
  "grade_counts": {
      "a": 3,
      "s": 2,
      "sh": 6,
      "ss": 2,
      "ssh": 3
  },
  "hit_accuracy": 92.19,
  "is_ranked": true,
  "level": {
      "current": 30,
      "progress": 0
  },
  "maximum_combo": 3948,
  "play_count": 228050,
  "play_time": null,
  "pp": 990,
  "global_rank": 87468,
  "ranked_score": 1502995536,
  "replays_watched_by_others": 0,
  "total_hits": 5856573,
  "total_score": 2104193750,
  "user": {
      "avatar_url": "https://a.ppy.sh/2?1519081077.png",
      "country": {
          "code": "AU",
          "name": "Australia"
      },
      "country_code": "AU",
      "cover": {
          "custom_url": null,
          "id": "3",
          "url": "https://assets.ppy.sh/user-profile-covers/2/baba245ef60834b769694178f8f6d4f6166c5188c740de084656ad2b80f1eea7.jpeg"
      },
      "default_group": "ppy",
      "id": 2,
      "is_active": false,
      "is_bot": false,
      "is_online": false,
      "is_supporter": true,
      "last_visit": "2019-02-22T11:07:10+00:00",
      "pm_friends_only": false,
      "profile_colour": "#3366FF",
      "username": "peppy"
  }
}


A summary of various gameplay statistics for a User. Specific to a Ruleset






Field
Type
Description






count_100
integer





count_300
integer





count_50
integer





count_miss
integer





country_rank
integer?
Current country rank according to pp.




grade_counts.a
integer
Number of A ranked scores.




grade_counts.s
integer
Number of S ranked scores.




grade_counts.sh
integer
Number of Silver S ranked scores.




grade_counts.ss
integer
Number of SS ranked scores.




grade_counts.ssh
integer
Number of Silver SS ranked scores.




hit_accuracy
float
Hit accuracy percentage




is_ranked
boolean
Is actively ranked




level.current
integer
Current level.




level.progress
float
Progress to next level.




maximum_combo
integer
Highest maximum combo.




play_count
integer
Number of maps played.




play_time
integer
Cumulative time played.




pp
float
Performance points




pp_exp
float
Experimental (lazer) performance points




global_rank
integer?
Current rank according to pp.




global_rank_exp
integer?
Current rank according to experimental (lazer) pp.




ranked_score
integer
Current ranked score.




replays_watched_by_others
integer
Number of replays watched by other users.




total_hits
integer
Total number of hits.




total_score
integer
Total score.






Optional attributes






Field
Type
Description






rank_change_since_30_days
integer?
Difference between current rank and rank 30 days ago, according to pp.




user
User






                    
WikiPage


{
    "available_locales": ["en", "id", "ja", "pt-br"],
    "layout": "markdown_page",
    "locale": "en",
    "markdown": "# osu! (game mode)\n\n![Gameplay of osu!](/wiki/shared/Interface_osu.jpg \"osu! Interface\")\n\nMarkdownMarkdownTruncated",
    "path": "Game_Modes/osu!",
    "subtitle": "Game Modes",
    "tags": ["tap", "circles"],
    "title": "osu! (game mode)"
}


Represents a wiki article






Field
Type
Description






available_locales
string[]
All available locales for the article.




layout
string
The layout type for the page.




locale
string
All lowercase BCP 47 language tag.




markdown
string
Markdown content.




path
string
Path of the article.




subtitle
string?
The article's subtitle.




tags
string[]
Associated tags for the article.




title
string
The article's title.