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

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

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   number  optional  

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  optional  

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   

The URL in your application where users will be sent after authorization.

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 number 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   number   

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 number 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   number   

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 number 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.write

Allows sending chat messages 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.

Beatmaps

Lookup Beatmap

OAuth public

Returns beatmap.

Example request:
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/beatmaps/lookup?checksum=delectus&filename=voluptate&id=itaque" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://osu.ppy.sh/api/v2/beatmaps/lookup"
);

const params = {
    "checksum": "delectus",
    "filename": "voluptate",
    "id": "itaque",
};
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/5/scores/users/1?mode=sit&mods=animi" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://osu.ppy.sh/api/v2/beatmaps/5/scores/users/1"
);

const params = {
    "mode": "sit",
    "mods": "animi",
};
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

mode   string  optional  

The GameMode 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/19/scores/users/17/all?mode=vitae" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://osu.ppy.sh/api/v2/beatmaps/19/scores/users/17/all"
);

const params = {
    "mode": "vitae",
};
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

mode   string  optional  

The GameMode to get scores for. Defaults to beatmap mode

Response Format

Field Type
scores Score[]

Get Beatmap scores

OAuth public

Returns the top scores for a beatmap

Example request:
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/beatmaps/2/scores?mode=nulla&mods=repellat&type=dolor" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://osu.ppy.sh/api/v2/beatmaps/2/scores"
);

const params = {
    "mode": "nulla",
    "mods": "repellat",
    "type": "dolor",
};
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

mode   string  optional  

The GameMode 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 (temp)

OAuth public

Returns the top scores for a beatmap from newer client.

This is a temporary endpoint.

Example request:
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/beatmaps/16/solo-scores?mode=et&mods=necessitatibus&type=quam" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://osu.ppy.sh/api/v2/beatmaps/16/solo-scores"
);

const params = {
    "mode": "et",
    "mods": "necessitatibus",
    "type": "quam",
};
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 GameMode 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 Beatmap[] 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/7" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://osu.ppy.sh/api/v2/beatmaps/7"
);

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 Beatmap 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   number|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   GameMode  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=nostrum&limit=2&page=2&sort=nostrum&types%5B%5D=et&user=quas&with_deleted=vero" \
    --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": "nostrum",
    "limit": "2",
    "page": "2",
    "sort": "nostrum",
    "types[]": "et",
    "user": "quas",
    "with_deleted": "vero",
};
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 BeatmapsetCompact
cursor_string CursorString
posts BeatmapsetDiscussionPost[]
users UserCompact

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=quo&limit=8&page=5&receiver=nesciunt&score=autem&sort=alias&user=veritatis&with_deleted=delectus" \
    --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": "quo",
    "limit": "8",
    "page": "5",
    "receiver": "nesciunt",
    "score": "autem",
    "sort": "alias",
    "user": "veritatis",
    "with_deleted": "delectus",
};
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 UserCompact
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=a&beatmapset_id=et&beatmapset_status=nesciunt&limit=6&message_types%5B%5D=suscipit&only_unresolved=dolores&page=20&sort=qui&user=veniam&with_deleted=aut" \
    --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": "a",
    "beatmapset_id": "et",
    "beatmapset_status": "nesciunt",
    "limit": "6",
    "message_types[]": "suscipit",
    "only_unresolved": "dolores",
    "page": "20",
    "sort": "qui",
    "user": "veniam",
    "with_deleted": "aut",
};
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.

Response Format

Field Type Description
beatmaps Beatmap[] 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 number Maximum number of blocks allowed in a review.
users UserCompact[] List of users associated with the discussions returned.

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": {
                "id": null,
                "display_name": "peppy",
                "github_url": 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=placeat" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://osu.ppy.sh/api/v2/changelog"
);

const params = {
    "message_formats[]": "placeat",
};
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": {
            "id": 218,
            "display_name": "bdach",
            "github_url": "https://github.com/bdach",
            "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 number Always 21.
search.max_id number? 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=autem" \
    --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[]": "autem",
};
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 lazer

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=4" \
    --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": "4",
};
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\": 6,
    \"message\": \"quaerat\",
    \"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": 6,
    "message": "quaerat",
    "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 lazer

This endpoint returns the chat messages for a specific channel.

Example request:
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/chat/channels/20/messages?limit=7&since=10&until=11" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://osu.ppy.sh/api/v2/chat/channels/20/messages"
);

const params = {
    "limit": "7",
    "since": "10",
    "until": "11",
};
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 lazer

This endpoint returns the chat messages for a specific channel.

Example request:
curl --request POST \
    "https://osu.ppy.sh/api/v2/chat/channels/6/messages" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"message\": \"voluptas\",
    \"is_action\": false
}"
const url = new URL(
    "https://osu.ppy.sh/api/v2/chat/channels/6/messages"
);

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

let body = {
    "message": "voluptas",
    "is_action": false
};

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 lazer

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

Example request:
curl --request PUT \
    "https://osu.ppy.sh/api/v2/chat/channels/voluptas/users/7" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://osu.ppy.sh/api/v2/chat/channels/voluptas/users/7"
);

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   integer   

The user.

Response Format

Returns the joined ChatChannel.

Leave Channel

requires user OAuth lazer

This endpoint allows you to leave a public channel.

Example request:
curl --request DELETE \
    "https://osu.ppy.sh/api/v2/chat/channels/et/users/20" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://osu.ppy.sh/api/v2/chat/channels/et/users/20"
);

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   integer   

The user.

Response Format

empty response

Mark Channel as Read

requires user OAuth lazer

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/placeat/mark-as-read/quia?channel_id=asperiores&message_id=id" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://osu.ppy.sh/api/v2/chat/channels/placeat/mark-as-read/quia"
);

const params = {
    "channel_id": "asperiores",
    "message_id": "id",
};
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 lazer

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

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 lazer

Gets details of a chat channel.

Example request:
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/chat/channels/possimus" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://osu.ppy.sh/api/v2/chat/channels/possimus"
);

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 UserCompact 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=sed&commentable_id=est&cursor=numquam&parent_id=nihil&sort=provident" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://osu.ppy.sh/api/v2/comments"
);

const params = {
    "commentable_type": "sed",
    "commentable_id": "est",
    "cursor": "numquam",
    "parent_id": "nihil",
    "sort": "provident",
};
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

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/20" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://osu.ppy.sh/api/v2/comments/20"
);

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   integer   

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/9" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://osu.ppy.sh/api/v2/comments/9"
);

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   integer   

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/14" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://osu.ppy.sh/api/v2/comments/14"
);

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   integer   

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/9/vote" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://osu.ppy.sh/api/v2/comments/9/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   integer   

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/13/vote" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://osu.ppy.sh/api/v2/comments/13/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   integer   

The comment.

Response Format

Returns CommentBundle

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   number   

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]   number  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]   number  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

cursor_string   string  optional  

Parameter for pagination.

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.

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=0&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": "0",
    "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   integer  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<UserCompact>? 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 number

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/5/playlist/2/scores/users/20" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://osu.ppy.sh/api/v2/rooms/5/playlist/2/scores/users/20"
);

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 MultiplayerScore object.

Get Scores

requires user OAuth public

Returns a list of scores for specified playlist item.

Example request:
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/rooms/18/playlist/16/scores?limit=11&sort=ut&cursor_string=ut" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://osu.ppy.sh/api/v2/rooms/18/playlist/16/scores"
);

const params = {
    "limit": "11",
    "sort": "ut",
    "cursor_string": "ut",
};
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 parameter.

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/16/playlist/7/scores/19" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://osu.ppy.sh/api/v2/rooms/16/playlist/7/scores/19"
);

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 MultiplayerScore object.

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 number 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 number[] All years during which posts have been published.
search.limit number 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=maiores" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://osu.ppy.sh/api/v2/notifications"
);

const params = {
    "max_id": "maiores",
};
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 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=0&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": "0",
    "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   

GameMode.

type   string   

RankingType.

Query Parameters

country   integer  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/beatmaps/{beatmap}/solo/scores

requires user OAuth lazer

Example request:
curl --request POST \
    "https://osu.ppy.sh/api/v2/beatmaps/17/solo/scores" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://osu.ppy.sh/api/v2/beatmaps/17/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   integer   

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/14/solo/scores/aut" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://osu.ppy.sh/api/v2/beatmaps/14/solo/scores/aut"
);

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   integer   

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/7/favourites" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://osu.ppy.sh/api/v2/beatmapsets/7/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   integer   

The beatmapset.

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

GET api/v2/matches

OAuth public

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());

Request

GET /matches

Headers

Content-Type      

Example: application/json

Accept      

Example: application/json

GET api/v2/matches/{match}

OAuth public

Example request:
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/matches/maiores" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://osu.ppy.sh/api/v2/matches/maiores"
);

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

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

Request

GET /matches/{match}

Headers

Content-Type      

Example: application/json

Accept      

Example: application/json

URL Parameters

match   string   

The match.

GET api/v2/rooms/{mode?}

requires user OAuth public

Example request:
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/rooms/owned|participated|ended" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://osu.ppy.sh/api/v2/rooms/owned|participated|ended"
);

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

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

Request

GET /rooms/{mode?}

Headers

Content-Type      

Example: application/json

Accept      

Example: application/json

URL Parameters

mode   string  optional  

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

requires user OAuth lazer

Example request:
curl --request PUT \
    "https://osu.ppy.sh/api/v2/rooms/occaecati/users/2" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://osu.ppy.sh/api/v2/rooms/occaecati/users/2"
);

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   integer   

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/enim/users/4" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://osu.ppy.sh/api/v2/rooms/enim/users/4"
);

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   integer   

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/assumenda/leaderboard" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://osu.ppy.sh/api/v2/rooms/assumenda/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/voluptas/playlist/dolorem/scores" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://osu.ppy.sh/api/v2/rooms/voluptas/playlist/dolorem/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/ratione/playlist/nihil/scores/ut" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://osu.ppy.sh/api/v2/rooms/ratione/playlist/nihil/scores/ut"
);

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/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

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/asperiores" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://osu.ppy.sh/api/v2/rooms/asperiores"
);

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.

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/{mode}/{score}/download

requires user OAuth public

Example request:
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/scores/aliquam/mollitia/download" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://osu.ppy.sh/api/v2/scores/aliquam/mollitia/download"
);

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

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

Request

GET /scores/{mode}/{score}/download

Headers

Content-Type      

Example: application/json

Accept      

Example: application/json

URL Parameters

mode   string   
score   string   

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

OAuth public

Example request:
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/scores/temporibus/fugit" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://osu.ppy.sh/api/v2/scores/temporibus/fugit"
);

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

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

Request

GET /scores/{mode}/{score}

Headers

Content-Type      

Example: application/json

Accept      

Example: application/json

URL Parameters

mode   string   
score   string   

GET api/v2/beatmapsets/search/{filters?}

OAuth public

Example request:
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/beatmapsets/search/et" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://osu.ppy.sh/api/v2/beatmapsets/search/et"
);

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

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

Request

GET /beatmapsets/search/{filters?}

Headers

Content-Type      

Example: application/json

Accept      

Example: application/json

URL Parameters

filters   string  optional  

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/13" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://osu.ppy.sh/api/v2/beatmapsets/13"
);

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   integer   

The beatmapset.

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

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/beatmapsets/{beatmapset}/download

OAuth lazer

Example request:
curl --request GET \
    --get "https://osu.ppy.sh/api/v2/beatmapsets/5/download" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://osu.ppy.sh/api/v2/beatmapsets/5/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   integer   

The beatmapset.

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  

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

Response format

See Get User.

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=14&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": "14",
    "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?include_fails=0&mode=osu&limit=2&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 = {
    "include_fails": "0",
    "mode": "osu",
    "limit": "2",
    "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

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  

GameMode 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
loved
most_played
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=3&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": "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}/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 Beatmapset, 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=11&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": "11",
    "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=atque" \
    --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": "atque",
};
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 username of the user. Id lookup is prioritised unless key parameter is specified. Previous usernames are also checked in some cases.

mode   string  optional  

GameMode. 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.

Response format

Returns User object. The following optional attributes on UserCompact 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.

Response format

Field Type Description
users UserCompact[] Includes: country, cover, groups, 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 when the 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 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 number[] 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 UserCompact[] 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.start' }));

Object Structures

Beatmap

Represent a beatmap. This extends BeatmapCompact 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

BeatmapCompact

Represent a beatmap.

Field Type Description
beatmapset_id integer
difficulty_rating float
id integer
mode GameMode
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|BeatmapsetCompact|null Beatmapset for Beatmap object, BeatmapsetCompact for BeatmapCompact 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

BeatmapPlaycount

Represent the playcount of a beatmap.

Field Type Description
beatmap_id number
beatmap BeatmapCompact?
beatmapset BeatmapsetCompact?
count number

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 number The position of the score within the requested beatmap ranking.
score Score The details of the score.

Beatmapset

Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.

Field Type Description
availability.download_disabled boolean
availability.more_information string?
bpm float
can_be_hyped boolean
creator string Username of the mapper at the time of beatmapset creation.
deleted_at string?
discussion_locked boolean
hype.current integer
hype.required integer
is_scoreable boolean
last_updated Timestamp
legacy_thread_url string?
nominations.current integer
nominations.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

BeatmapsetCompact

Represents a beatmapset.

Field Type Description
artist string
artist_unicode string
covers Covers
creator string
favourite_count number
id number
nsfw boolean
play_count number
preview_url string
source string
status string
title string
title_unicode string
user_id number
video boolean

Those fields are optional.

Field Type Description
beatmaps Beatmap[]
converts
current_user_attributes
description
discussions
events
genre
has_favourited boolean
language
nominations
pack_tags string[]
ratings
recent_favourites
related_users
user

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 BeatmapCompact?
beatmap_id number?
beatmapset BeatmapsetCompact?
beatmapset_id number
can_be_resolved boolean
can_grant_kudosu boolean
created_at Timestamp
current_user_attributes CurrentUserAttributes
deleted_at Timestamp?
deleted_by_id number?
id number
kudosu_denied boolean
last_post_at Timestamp
message_type MessageType
parent_id number?
posts BeatmapsetDiscussionPost[]?
resolved boolean
starting_post BeatmapsetDiscussionPost?
timestamp number?
updated_at Timestamp
user_id number

MessageType

Name Description
hype
mapper_note
praise
problem
review
suggestion

BeatmapsetDiscussionPost

Represents a post in a BeatmapsetDiscussion.

Field Type Description
beatmapset_discussion_id number
created_at Timestamp
deleted_at Timestamp?
deleted_by_id number?
id number
last_editor_id number?
message string
system boolean
updated_at Timestamp
user_id number

BeatmapsetDiscussionVote

Represents a vote on a BeatmapsetDiscussion.

Field Type Description
beatmapset_discussion_id number
created_at Timestamp
id number
score number
updated_at Timestamp
user_id number

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 number
update_stream UpdateStream?
users number
version 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 number?
github_url string?
id number?
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 number
name string
description string?
icon string? display icon for the channel
type ChannelType type of channel
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 number? Deprecated; use current_user_attributes.last_read_id.
last_message_id number? message_id of last known message (only returned in presence responses)
recent_messages ChatMessage[]? Deprecated; up to 50 most recent messages
users number[]? 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 number channel_id of where the message was sent
content string message content
content_html string? Deprecated. Markdown message content as HTML
is_action boolean was this an action? i.e. /me dances
message_id number unique identifier for message
sender_id number user_id of the sender
timestamp string 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 UserCompact embedded UserCompact 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 an single comment.

Field Type Description
commentable_id number ID of the object the comment is attached to
commentable_type string type of object the comment is attached to
created_at string ISO 8601 date
deleted_at string? ISO 8601 date if the comment was deleted; null, otherwise
edited_at string? ISO 8601 date if the comment was edited; null, otherwise
edited_by_id number? user id of the user that edited the post; null, otherwise
id number 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 number? ID of the comment's parent
pinned boolean Pin status of the comment
replies_count number number of replies to the comment
updated_at string ISO 8601 date
user_id number user ID of the poster
votes_count number 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 number?
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 number? Number of comments at the top level. Not returned for replies.
total number? Total number of comments. Not retuned for replies.
user_follow boolean is the current user watching the comment thread?
user_votes number[] IDs of the comments in the bundle the current user has upvoted
users UserCompact[] 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 number the ID of the object
owner_id number? 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 number 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 number
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 number

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 number
mode GameMode
beatmap Event.Beatmap
user Event.User

rankLost

When a user loses first place to another user.

Field Type
mode GameMode
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 number?
forum_id number
id number
topic_id number
user_id number

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 number
forum_id number
id number
is_locked boolean
last_post_id number
poll Poll?
post_count number
title string
type normal | sticky | announcement
updated_at Timestamp
user_id number

Poll

Field Type
allow_vote_change boolean
ended_at Timestamp?
hide_incomplete_results boolean
last_vote_at Timestamp?
max_votes number
options PollOption[]
started_at Timestamp
title.bbcode string
title.html string
total_vote_count number

PollOption

Field Type Notes
id number Unique only per-topic.
text.bbcode string
text.html string
vote_count number? Not present if the poll is incomplete and results are hidden.

GameMode

Available game modes:

Name Description
fruits osu!catch
mania osu!mania
osu osu!standard
taiko osu!taiko

GithubUser

{
  "id": 218,
  "display_name": "bdach",
  "github_url": "https://github.com/bdach",
  "osu_username": null,
  "user_id": null,
  "user_url": null
}
Field Type
display_name string
github_url string?
id number?
osu_username string?
user_id number?
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 GameModes with users' memberships.
id number
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 number
action string One of give, vote.give, reset, vote.reset, revoke, or vote.revoke.
amount number
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.

MultiplayerScore

Score data.

Field Type Description
id number
user_id number
room_id number
playlist_item_id number
beatmap_id number
rank rank
total_score number
accuracy number
max_combo number
mods Mod[]
statistics Statistics
passed bool
position number?
scores_around MultiplayerScoresAround? Scores around the specified score.
user User

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 MultiplayerScore[]
total number? Index only. Total scores of the specified playlist item.
user_score MultiplayerScore? 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 number Last score id of current result (score_asc, score_desc).
total_score number 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.
id number
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.

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 number
name string Name of the event
created_at string ISO 8601 date
object_type string
object_id number
source_user_id number?
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 number Beatmapset id
object_type string beatmapset
source_user_id number 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 number Beatmapset id
object_type string beatmapset
source_user_id number Poster of the discussion

Details object:

Field Type Description
title string Beatmap title
cover_url string Beatmap cover
discussion_id number
post_id number
beatmap_id number? null if posted to general all
username string Username of source_user_id

beatmapset_discussion_unlock

Field Type Description
object_id number Beatmapset id
object_type string beatmapset
source_user_id number 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 number Beatmapset id
object_type string beatmapset
source_user_id number 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 number Beatmapset id
object_type string beatmapset
source_user_id number 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 number Beatmapset id
object_type string beatmapset
source_user_id number 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 number Beatmapset id
object_type string beatmapset
source_user_id number 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 number Beatmapset id
object_type string beatmapset
source_user_id number 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 number Beatmapset id
object_type string beatmapset
source_user_id number 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 number Channel id
object_type string channel
source_user_id number 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 number Topic id
object_type string forum_topic
source_user_id number User who posted message

Details object:

Field Type Description
title string Title of the replied topic
cover_url string Topic cover
post_id number 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 Beatmapset[]? The list of beatmaps in the requested spotlight for the given mode; only available if type is charts
cursor Cursor A cursor
ranking UserStatistics[] Score details ordered by rank in descending order.
spotlight Spotlight? Spotlight details; only available if type is charts
total number An approximate count of ranks available

Score

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
rank_country
rank_global
weight
user
match

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 DateTime The end date of the spotlight.
id number The ID of this spotlight.
mode_specific boolean If the spotlight has different mades specific to each GameMode.
participant_count number? 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 DateTime 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 number
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 number

User

{
  "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_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_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 UserCompact 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 ever being a supporter in the past
interests string?
join_date Timestamp
kudosu.available number
kudosu.total number
location string?
max_blocks number maximum number of users allowed to be blocked
max_friends number maximum number of friends allowed to be added
occupation string?
playmode GameMode
playstyle string[] Device choices of the user.
post_count number number of forum posts
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 UserCompact are included:

ProfilePage

Section
me
recent_activity
beatmaps
historical
kudosu
top_ranks
medals

UserCompact

{
  "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
}

Mainly used for embedding in certain responses to save additional api lookups.

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 number 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
account_history UserAccountHistory[]
active_tournament_banner UserCompact.ProfileBanner?
badges UserBadge[]
beatmap_playcounts_count number
blocks
country
cover
favourite_beatmapset_count number
follower_count number
friends
graveyard_beatmapset_count number
groups UserGroup[]
is_restricted boolean?
loved_beatmapset_count number
monthly_playcounts UserMonthlyPlaycount[]
page
pending_beatmapset_count
previous_usernames
rank_highest RankHighest?
rank_history
ranked_beatmapset_count
replays_watched_counts
scores_best_count number
scores_first_count number
scores_recent_count number
statistics
statistics_rulesets UserStatisticsRulesets
support_level
unread_pm_count
user_achievements
user_preferences

ProfileBanner

Field Type Description
id number
tournament_id number
image string

RankHighest

Field Type
rank number
updated_at Timestamp

UserAccountHistory

Field Type Description
description string?
id number
length number In seconds.
permanent boolean
timestamp Timestamp
type string note, restriction, or silence.

UserBadge

Field Type Description
awarded_at Timestamp
description string
image_url string
url string

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[]? GameModes 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 number id of this object.
user_id number 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 GameMode

Field Type Description
count_100 number
count_300 number
count_50 number
count_miss number
grade_counts.a number Number of A ranked scores.
grade_counts.s number Number of S ranked scores.
grade_counts.sh number Number of Silver S ranked scores.
grade_counts.ss number Number of SS ranked scores.
grade_counts.ssh number Number of Silver SS ranked scores.
hit_accuracy number Hit accuracy percentage
is_ranked boolean Is actively ranked
level.current number Current level.
level.progress number Progress to next level.
maximum_combo number Highest maximum combo.
play_count number Number of maps played.
play_time number Cumulative time played.
pp number Performance points
global_rank number? Current rank according to pp.
ranked_score number Current ranked score.
replays_watched_by_others number Number of replays watched by other users.
total_hits number Total number of hits.
total_score number Total score.
user UserCompact The associated 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.