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.

• ossapi (python)
• aiosu (python)
• osu.py (python)
• rosu-v2 (rust)
• osu.js (javascript/typescript)
• osu-api-v2-js (javascript/typescript)

Changelog

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

Breaking Changes

2025-04-10

• /beatmaps/{beatmap}/solo-scores endpoint has been deprecated. Use /beatmaps/{beatmap}/scores instead.

2024-07-30

• key parameter for Get User endpoint has been deprecated. Prefix username with @ to lookup by username instead.

2024-01-23

• active_tournament_banner in User has been deprecated, use active_tournament_banners instead.

2023-10-17

• GameMode has been renamed to Ruleset; existing property names remain unchanged.
• number has been removed from documentation and replaced with integer or float to better reflect the type of number.

2023-09-11

• object structures with two main variants (Beatmap, Beatmapset, and User) have their naming changed. The base object which previously has Compact suffix has their suffix removed and the previously extended object with no suffix now has Extended suffix instead. This matches existing TypeScript interface.

2023-02-17

• content_html in ChatMessage has been deprecated; pre-rendered markdown will be removed.

2023-01-05

• new_channel_id in Create New PM response has been deprecated, use channel.channel_id instead.

2022-11-21

• messages has been removed from Chat Get Updates.

2022-11-11

• recent_messages in ChatChannel has been deprecated, it will be removed from Create Channel response in the near future.

2022-09-27

• user include in Get User Scores response has been deprecated, it will be removed in the near future.

2022-07-06

• chat/presence endpoint has been deprecated, it will be removed in the near future.

2022-06-08

• discussion_enabled in Beatmapset is deprecated. All beatmapsets now have it enabled.

2021-10-28

• beatmap in Get Beatmap scores scores array item is removed (it's never been documented in the first place).

2021-09-01

• last_read_id in ChatChannel is deprecated, use current_user_attributes.last_read_id instead.

2021-08-11

• bot scope removed in favour for delegate scope Client Credentials Delegation.

2021-06-14

• Removed description from UserGroup. It has been moved to an optional attribute with a different type on Group.

2021-06-09

• ranked_and_approved_beatmapset_count and unranked_beatmapset_count attributes in UserCompact object have been deprecated and replaced with ranked_beatmapset_count and pending_beatmapset_count respectively.
• ranked_and_approved and unranked types in Get User Beatmaps have been deprecated and replaced with ranked and pending respectively.

2021-04-20

• cover_url in User is deprecated, use cover.url instead.

2021-02-25

• current_mode_rank has been removed from UserCompact
• attributes in UserStatistics have been moved around
  • rank.country is deprecated, replaced by country_rank
  • rank.global and pp_rank are removed, replaced by global_rank

2020-09-08

• presence removed from chat/new response.

2020-08-28

• /rooms/{room_id}/leaderboard no longer returns an array at the top level; an object with keys is now returned.

2020-05-01

• users.read scope removed, replaced with more general public scope.

2020-02-18

• Beatmap max_combo and build update stream user_count now return the values as primitives instead of numbers wrapped in an array.

2019-10-09

• Ranking API response no longer returns an array at the top level; an object with keys is now returned.

2019-07-18

• User now returns counts directly as primitives instead of numbers wrapped in an array.

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.

API Response Version

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

Version 0 is assumed when the header is omitted.

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:

• Authorization Code Grant
• Client Credentials Grant

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:

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:

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

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:

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,
}).then(response => response.json());

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

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

Response Format

Successful requests will be issued an access 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:

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,
}).then(response => response.json());

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

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

Response Format

Successful requests will be issued an access token and a new 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:

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,
}).then(response => response.json());

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

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

Response Format

Successful requests will be issued an 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:

Scopes

The following scopes are currently supported:

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

• a Chat Bot account to send messages on behalf of other users.
• Authorization code grant where the user is the same as the client's owner (send as yourself).

Managing OAuth applications

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

Reset Client Secret

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

Beatmap Packs

Get Beatmap Packs

OAuth public

Returns a list of beatmap packs.

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

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

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

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

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

Request

GET /beatmaps/packs

Response format

Get Beatmap Pack

OAuth public

Gets the beatmap pack for the specified beatmap pack tag.

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

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

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

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

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

Request

GET /beatmaps/packs/{pack}

Response format

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

Beatmaps

Lookup Beatmap

OAuth public

Returns beatmap.

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

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

const params = {
    "checksum": "mollitia",
    "filename": "voluptatem",
    "id": "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());

"See Beatmap object section"
 

Request

GET /beatmaps/lookup

Response format

See Get Beatmap

Get a User Beatmap score

OAuth public

Return a User's score on a Beatmap

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

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

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

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

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

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

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

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

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

Request

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

Response Format

Get Beatmap scores

OAuth public

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

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

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

const params = {
    "legacy_only": "0",
    "mode": "laborum",
    "mods": "sit",
    "type": "odio",
};
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

Response Format

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

Get Beatmap scores (non-legacy)

OAuth public

Returns the top scores for a beatmap.

This endpoint is deprecated. Use Get Beatmap scores with appropriate api version header instead.

curl --request GET \
    --get "https://osu.ppy.sh/api/v2/beatmaps/14/solo-scores?mode=cumque&mods=vero&type=odio" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

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

const params = {
    "mode": "cumque",
    "mods": "vero",
    "type": "odio",
};
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

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.

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

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

Request

GET /beatmaps

Response format

Get Beatmap

OAuth public

Gets beatmap data for the specified beatmap ID.

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

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

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

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

"See Beatmap object section."
 

Request

GET /beatmaps/{beatmap}

Response format

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

Get Beatmap Attributes

OAuth public

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

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

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

Request

POST /beatmaps/{beatmap}/attributes

Response format

Beatmapset Discussions

Get Beatmapset Discussion Posts

OAuth public

Returns the posts of beatmapset discussions.

curl --request GET \
    --get "https://osu.ppy.sh/api/v2/beatmapsets/discussions/posts?beatmapset_discussion_id=cumque&limit=2&page=7&sort=sed&types%5B%5D=fugiat&user=quisquam&with_deleted=blanditiis" \
    --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": "cumque",
    "limit": "2",
    "page": "7",
    "sort": "sed",
    "types[]": "fugiat",
    "user": "quisquam",
    "with_deleted": "blanditiis",
};
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

Response Format

Get Beatmapset Discussion Votes

OAuth public

Returns the votes given to beatmapset discussions.

curl --request GET \
    --get "https://osu.ppy.sh/api/v2/beatmapsets/discussions/votes?beatmapset_discussion_id=ut&limit=13&page=17&receiver=et&score=fugit&sort=perferendis&user=architecto&with_deleted=ipsam" \
    --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": "ut",
    "limit": "13",
    "page": "17",
    "receiver": "et",
    "score": "fugit",
    "sort": "perferendis",
    "user": "architecto",
    "with_deleted": "ipsam",
};
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

Response Format

Get Beatmapset Discussions

OAuth public

Returns a list of beatmapset discussions.

curl --request GET \
    --get "https://osu.ppy.sh/api/v2/beatmapsets/discussions?beatmap_id=et&beatmapset_id=consequatur&beatmapset_status=ut&limit=8&message_types%5B%5D=quos&only_unresolved=facilis&page=14&sort=et&user=et&with_deleted=molestiae" \
    --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": "et",
    "beatmapset_id": "consequatur",
    "beatmapset_status": "ut",
    "limit": "8",
    "message_types[]": "quos",
    "only_unresolved": "facilis",
    "page": "14",
    "sort": "et",
    "user": "et",
    "with_deleted": "molestiae",
};
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

Response Format

Beatmapsets

Search Beatmapset

OAuth public

TODO: documentation

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

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

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

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

Request

GET /beatmapsets/search

GET api/v2/beatmapsets/lookup

OAuth public

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

GET api/v2/beatmapsets/{beatmapset}

OAuth public

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

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

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

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

Request

GET /beatmapsets/{beatmapset}

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

OAuth lazer

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

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

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

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

Request

GET /beatmapsets/{beatmapset}/download

Changelog

Get Changelog Build

Returns details of the specified build.

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

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

Request

GET /changelog/{stream}/{build}

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.

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

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

const params = {
    "message_formats[]": "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());

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

Request

GET /changelog

Response Format

Lookup Changelog Build

Returns details of the specified build.

curl --request GET \
    --get "https://osu.ppy.sh/api/v2/changelog/20210520.2?message_formats%5B%5D=enim" \
    --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[]": "enim",
};
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());

See "Get Changelog Build" response.
 

Request

GET /changelog/{changelog}

Response Format

See Get Changelog Build.

Chat

Chat Keepalive

requires user OAuth chat.read

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

See Public channels and activity timeout

curl --request POST \
    "https://osu.ppy.sh/api/v2/chat/ack?history_since=1" \
    --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": "1",
};
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

Response Format

Create New PM

requires user OAuth chat.write

This endpoint allows you to create a new PM channel.

curl --request POST \
    "https://osu.ppy.sh/api/v2/chat/new" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"target_id\": 11,
    \"message\": \"delectus\",
    \"is_action\": true,
    \"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": 11,
    "message": "delectus",
    "is_action": true,
    "uuid": "some-uuid-string"
};

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

{
  "channel": {
    "channel_id": 1234,
    "description": "",
    "icon": "https://a.ppy.sh/102?1500537068"
    "message_length_limit": 450,
    "moderated": false,
    "name": "peppy",
    "type": "PM",
    "uuid": null,
    "last_message_id": 9150005005,
    "users": [
      101,
      102
    ]
  },
  "message": {
    "channel_id": 1234,
    "content": "i can haz featured artist plz?",
    "is_action": false,
    "message_id": 9150005005,
    "sender_id": 102,
    "timestamp": "2024-12-23T01:23:45+00:00",
    "type": "plain",
    "uuid": "some-uuid-string",
    "sender": {
      "avatar_url": "https://a.ppy.sh/102?1500537068",
      "country_code": "AU",
      "default_group": "default",
      "id": 102,
      "is_active": true,
      "is_bot": false,
      "is_deleted": false,
      "is_online": true,
      "is_supporter": true
      "last_visit": "2024-12-23T01:23:45+00:00",
      "pm_friends_only": false,
      "profile_colour": "#333333",
      "username": "nekodex",
    }
  },
  "new_channel_id": 1234,
}
 

Request

POST /chat/new

Response Format

Get Updates

requires user OAuth lazer

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

curl --request GET \
    --get "https://osu.ppy.sh/api/v2/chat/updates?history_since=13" \
    --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": "13",
};
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());

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

Response Format

Get Channel Messages

requires user OAuth chat.read

This endpoint returns the chat messages for a specific channel.

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

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

const params = {
    "limit": "11",
    "since": "5",
    "until": "6",
};
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());

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

Response Format

Returns an array of ChatMessage

Send Message to Channel

requires user OAuth chat.write

This endpoint returns the chat messages for a specific channel.

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

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

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

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

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

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

Response Format

The sent ChatMessage

Join Channel

requires user OAuth chat.write_manage

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

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

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

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

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

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

Response Format

Returns the joined ChatChannel.

Leave Channel

requires user OAuth chat.write_manage

This endpoint allows you to leave a public channel.

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

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

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

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

[Empty response]
 

Request

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

Response Format

empty response

Mark Channel as Read

requires user OAuth chat.read

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

curl --request PUT \
    "https://osu.ppy.sh/api/v2/chat/channels/maxime/mark-as-read/aut?channel_id=cumque&message_id=consequuntur" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

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

const params = {
    "channel_id": "cumque",
    "message_id": "consequuntur",
};
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());

[Empty response]
 

Request

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

Response Format

empty response

Get Channel List

requires user OAuth chat.read

This endpoint returns a list of all joinable public channels.

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

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

Response Format

Returns an array of ChatChannel

Create Channel

requires user OAuth chat.write_manage

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

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

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

Response Format

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

Get Channel

requires user OAuth chat.read

Gets details of a chat channel.

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

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

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

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

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

Response Format

Comments

Get Comments

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

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

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

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

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

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

Request

GET /comments

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.

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

Response Format

Returns CommentBundle

Get a Comment

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

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

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

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

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

Request

GET /comments/{comment}

Response Format

Returns CommentBundle

Edit Comment

requires user OAuth lazer

Edit an existing comment.

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

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

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}

Response Format

Returns CommentBundle

Delete Comment

requires user OAuth lazer

Deletes the specified comment.

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

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

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

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

Request

DELETE /comments/{comment}

Response Format

Returns CommentBundle

Add Comment vote

requires user OAuth lazer

Upvotes a comment.

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

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

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

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

Request

POST /comments/{comment}/vote

Response Format

Returns CommentBundle

Remove Comment vote

requires user OAuth lazer

Un-upvotes a comment.

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

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

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

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

Request

DELETE /comments/{comment}/vote

Response Format

Returns CommentBundle

Events

Get Events

OAuth public

Returns a collection of Events in order of creation time.

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

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

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

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

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

Request

GET /events

Response Format

Forum

Reply Topic

requires user OAuth forum.write

Create a post replying to the specified topic.

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

Response Format

ForumPost with body included.

Get Topic Listing

OAuth public

Get a sorted list of topics, optionally from a specific forum

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

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

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

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

{
    "topics": [
        {
            "id": 1,
            "...": "..."
        },
        {
            "id": 2,
            "...": "..."
        }
    ],
    "cursor_string": "eyJoZWxsbyI6IndvcmxkIn0"
}
 

Request

GET /forums/topics

Response Format

Create Topic

requires user OAuth forum.write

Create a new topic.

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

Response Format

Get Topic and Posts

OAuth public

Get topic and its posts.

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

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

Request

GET /forums/topics/{topic}

Response Format

Edit Topic

OAuth forum.write

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

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}

Response Format

The edited ForumTopic.

Edit Post

OAuth forum.write

Edit specified forum post.

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