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.

Refer to the list of Scopes for which scopes 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 any of the chat.read chat.write chat.write_manage scopes 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.

Account

GET api/v2/me/beatmapset-favourites

requires user OAuth identify

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

const url = new URL( "https://osu.ppy.sh/api/v2/me/beatmapset-favourites" ); const headers = { "Content-Type": "application/json", "Accept": "application/json", }; fetch(url, { method: "GET", headers, }).then(response => response.json());

Request

GET /me/beatmapset-favourites

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=neque" \ --header "Content-Type: application/json" \ --header "Accept: application/json"

const url = new URL( "https://osu.ppy.sh/api/v2/beatmaps/packs" ); const params = { "type": "neque", }; 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/id?legacy_only=0" \ --header "Content-Type: application/json" \ --header "Accept: application/json"

const url = new URL( "https://osu.ppy.sh/api/v2/beatmaps/packs/id" ); 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=quibusdam&filename=eum&id=id" \ --header "Content-Type: application/json" \ --header "Accept: application/json"

const url = new URL( "https://osu.ppy.sh/api/v2/beatmaps/lookup" ); const params = { "checksum": "quibusdam", "filename": "eum", "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: "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/5/scores/users/18?legacy_only=0&mode=fugiat&mods=quis" \ --header "Content-Type: application/json" \ --header "Accept: application/json"

const url = new URL( "https://osu.ppy.sh/api/v2/beatmaps/5/scores/users/18" ); const params = { "legacy_only": "0", "mode": "fugiat", "mods": "quis", }; 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/7/scores/users/4/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/7/scores/users/4/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/16/scores?legacy_only=0&mode=dolorum&mods=aut&type=qui" \ --header "Content-Type: application/json" \ --header "Accept: application/json"

const url = new URL( "https://osu.ppy.sh/api/v2/beatmaps/16/scores" ); const params = { "legacy_only": "0", "mode": "dolorum", "mods": "aut", "type": "qui", }; 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/12/solo-scores?mode=error&mods=at&type=magni" \ --header "Content-Type: application/json" \ --header "Accept: application/json"

const url = new URL( "https://osu.ppy.sh/api/v2/beatmaps/12/solo-scores" ); const params = { "mode": "error", "mods": "at", "type": "magni", }; 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/19" \ --header "Content-Type: application/json" \ --header "Accept: application/json"

const url = new URL( "https://osu.ppy.sh/api/v2/beatmaps/19" ); 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=ea&limit=14&page=18&sort=magni&types%5B%5D=perferendis&user=quidem&with_deleted=sed" \ --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": "ea", "limit": "14", "page": "18", "sort": "magni", "types[]": "perferendis", "user": "quidem", "with_deleted": "sed", }; 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=aut&limit=8&page=3&receiver=rem&score=doloribus&sort=quis&user=molestiae&with_deleted=nesciunt" \ --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": "aut", "limit": "8", "page": "3", "receiver": "rem", "score": "doloribus", "sort": "quis", "user": "molestiae", "with_deleted": "nesciunt", }; 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=facere&beatmapset_id=dolore&beatmapset_status=eum&limit=8&message_types%5B%5D=placeat&only_unresolved=libero&page=1&sort=officia&user=fuga&with_deleted=sint" \ --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": "facere", "beatmapset_id": "dolore", "beatmapset_status": "eum", "limit": "8", "message_types[]": "placeat", "only_unresolved": "libero", "page": "1", "sort": "officia", "user": "fuga", "with_deleted": "sint", }; 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/numquam" \ --header "Content-Type: application/json" \ --header "Accept: application/json"

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

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

const url = new URL( "https://osu.ppy.sh/api/v2/changelog" ); const params = { "message_formats[]": "porro", }; 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=tenetur" \ --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[]": "tenetur", }; 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=15" \ --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": "15", }; 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\": \"ut\", \"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": "ut", "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=19" \ --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": "19", }; 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/20/messages?limit=13&since=11&until=4" \ --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": "13", "since": "11", "until": "4", }; 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/8/messages" \ --header "Content-Type: application/json" \ --header "Accept: application/json" \ --data "{ \"message\": \"fugit\", \"is_action\": false }" 

const url = new URL( "https://osu.ppy.sh/api/v2/chat/channels/8/messages" ); const headers = { "Content-Type": "application/json", "Accept": "application/json", }; let body = { "message": "fugit", "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/at/users/similique" \ --header "Content-Type: application/json" \ --header "Accept: application/json"

const url = new URL( "https://osu.ppy.sh/api/v2/chat/channels/at/users/similique" ); 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/fugit/users/hic" \ --header "Content-Type: application/json" \ --header "Accept: application/json"

const url = new URL( "https://osu.ppy.sh/api/v2/chat/channels/fugit/users/hic" ); 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/sunt/mark-as-read/saepe?channel_id=molestiae&message_id=quo" \ --header "Content-Type: application/json" \ --header "Accept: application/json"

const url = new URL( "https://osu.ppy.sh/api/v2/chat/channels/sunt/mark-as-read/saepe" ); const params = { "channel_id": "molestiae", "message_id": "quo", }; 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/quia" \ --header "Content-Type: application/json" \ --header "Accept: application/json"

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

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

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

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

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

const url = new URL( "https://osu.ppy.sh/api/v2/comments/earum/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

Lock Topic

requires user OAuth forum.write_manage

Locks a Topic

curl --request POST \ "https://osu.ppy.sh/api/v2/forums/topics/12/lock?lock=" \ --header "Content-Type: application/json" \ --header "Accept: application/json"

const url = new URL( "https://osu.ppy.sh/api/v2/forums/topics/12/lock" ); const params = { "lock": "0", }; 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());

[Empty response] 

Request

POST /forums/topics/{topic}/lock

Response Format

empty response

POST api/v2/forums/topics/{topic}/move

OAuth lazer

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

const url = new URL( "https://osu.ppy.sh/api/v2/forums/topics/voluptates/move" ); const headers = { "Content-Type": "application/json", "Accept": "application/json", }; fetch(url, { method: "POST", headers, }).then(response => response.json());

Request

POST /forums/topics/{topic}/move

Pin Topic

requires user OAuth forum.write_manage

Pins a Topic

curl --request POST \ "https://osu.ppy.sh/api/v2/forums/topics/11/pin?pin=1" \ --header "Content-Type: application/json" \ --header "Accept: application/json"

const url = new URL( "https://osu.ppy.sh/api/v2/forums/topics/11/pin" ); const params = { "pin": "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());

[Empty response] 

Request

POST /forums/topics/{topic}/pin

Response Format

empty response

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

Request

PUT /forums/posts/{post}

PATCH /forums/posts/{post}

Response Format

ForumPost with body included.

Get Forum Listing

OAuth public

Get top-level forums and their subforums (max 2 deep).

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

const url = new URL( "https://osu.ppy.sh/api/v2/forums" ); const headers = { "Content-Type": "application/json", "Accept": "application/json", }; fetch(url, { method: "GET", headers, }).then(response => response.json());

 { "forums": [ { "forum_id": 1, "...": "..." }, { "forum_id": 2, "...": "..." } ] } 

Request

GET /forums

Response Format

Get Forum and Topics

OAuth public

Get a forum by id, its pinned topics, recent topics, and its subforums.

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

const url = new URL( "https://osu.ppy.sh/api/v2/forums/1" ); const headers = { "Content-Type": "application/json", "Accept": "application/json", }; fetch(url, { method: "GET", headers, }).then(response => response.json());

 { "forum": { "id": 1, "...": "..." }, "topics": [ { "id": 1, "...": "..." }, { "id": 2, "...": "..." }, ], "pinned_topics": [ { "id": 1, "...": "..." }, { "id": 2, "...": "..." }, ] } 

Request

GET /forums/{forum}

Response Format

Home

Search

OAuth public

Searches users and wiki pages.

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

const url = new URL( "https://osu.ppy.sh/api/v2/search" ); const params = { "mode": "all", "query": "hello", "page": "1", }; Object.keys(params) .forEach(key => url.searchParams.append(key, params[key])); const headers = { "Content-Type": "application/json", "Accept": "application/json", }; fetch(url, { method: "GET", headers, }).then(response => response.json());

Request

GET /search

Response Format

SearchResult<T>

Matches

Get Matches Listing

OAuth public

Returns a list of matches.

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

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

Request

GET /matches

Response Format

Get Match

OAuth public

Returns details of the specified match.

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

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

Request

GET /matches/{match}

Response Format

Multiplayer

Get User High Score

requires user OAuth lazer

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

curl --request GET \ --get "https://osu.ppy.sh/api/v2/rooms/5/playlist/10/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/10/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}

Response Format

Returns Score object.

Get Scores

OAuth public

Returns a list of scores for specified playlist item.

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

const url = new URL( "https://osu.ppy.sh/api/v2/rooms/9/playlist/3/scores" ); const params = { "limit": "16", "sort": "eaque", }; 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

Response Format

Returns MultiplayerScores object.

Get a Score

requires user OAuth lazer

Returns detail of specified score and the surrounding scores.

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

const url = new URL( "https://osu.ppy.sh/api/v2/rooms/1/playlist/12/scores/10" ); 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}

Response Format

Returns Score object.

Get Multiplayer Rooms

OAuth public

Returns a list of multiplayer rooms.

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

const url = new URL( "https://osu.ppy.sh/api/v2/rooms" ); const headers = { "Content-Type": "application/json", "Accept": "application/json", }; fetch(url, { method: "GET", headers, }).then(response => response.json());

Request

GET /rooms

News

Get News Listing

Returns a list of news posts and related metadata.

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

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

Response Format

Get News Post

Returns details of the specified news post.

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

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

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.

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

const url = new URL( "https://osu.ppy.sh/api/v2/notifications" ); const params = { "max_id": "alias", }; 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());

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

Response Format

Returns an object containing Notification and other related attributes.

Mark Notifications as Read

requires user OAuth lazer

This endpoint allows you to mark notifications read.

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

[Empty response] 

Request

POST /notifications/mark-read

Response Format

empty response

OAuth Tokens

Revoke current token

OAuth

Revokes currently authenticated token.

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

[Empty response] 

Request

DELETE /oauth/tokens/current

Ranking

Get Kudosu Ranking

OAuth public

Gets the kudosu ranking.

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

const url = new URL( "https://osu.ppy.sh/api/v2/rankings/kudosu" ); const params = { "page": "1", }; Object.keys(params) .forEach(key => url.searchParams.append(key, params[key])); const headers = { "Content-Type": "application/json", "Accept": "application/json", }; fetch(url, { method: "GET", headers, }).then(response => response.json());

Request

GET /rankings/kudosu

Response format

Get Ranking

OAuth public

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

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

const url = new URL( "https://osu.ppy.sh/api/v2/rankings/expedita/global" ); const params = { "country": "JP", "filter": "all", "variant": "4k", }; Object.keys(params) .forEach(key => url.searchParams.append(key, params[key])); const headers = { "Content-Type": "application/json", "Accept": "application/json", }; fetch(url, { method: "GET", headers, }).then(response => response.json());

Request

GET /rankings/{mode}/{type}

Response Format

Returns Rankings

Get Spotlights

OAuth public

Gets the list of spotlights.

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

Response Format

Returns Spotlights

Scores

Get Scores

OAuth public

Returns all passed scores. Up to 1000 scores will be returned in order of oldest to latest. Most recent scores will be returned if cursor_string parameter is not specified.

Obtaining new scores that arrived after the last request can be done by passing cursor_string parameter from the previous request.

curl --request GET \ --get "https://osu.ppy.sh/api/v2/scores?ruleset=eos&cursor_string=rerum" \ --header "Content-Type: application/json" \ --header "Accept: application/json"

const url = new URL( "https://osu.ppy.sh/api/v2/scores" ); const params = { "ruleset": "eos", "cursor_string": "rerum", }; 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 /scores

Response Format

Reorder Pinned Score

requires user OAuth lazer

Changes pinned position of a score on the user's profile.

curl --request POST \ "https://osu.ppy.sh/api/v2/score-pins/19/reorder" \ --header "Content-Type: application/json" \ --header "Accept: application/json" \ --data "{ \"after_score_id\": 14 }" 

const url = new URL( "https://osu.ppy.sh/api/v2/score-pins/19/reorder" ); const headers = { "Content-Type": "application/json", "Accept": "application/json", }; let body = { "after_score_id": 14 }; fetch(url, { method: "POST", headers, body: JSON.stringify(body), }).then(response => response.json());

[Empty response] 

Request

POST /score-pins/{score}/reorder

Response Format

empty response

Unpin Score

requires user OAuth lazer

Unpins a score from the user's profile.

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

const url = new URL( "https://osu.ppy.sh/api/v2/score-pins/16" ); const headers = { "Content-Type": "application/json", "Accept": "application/json", }; fetch(url, { method: "DELETE", headers, }).then(response => response.json());

[Empty response] 

Request

DELETE /score-pins/{score}

Response Format

empty response

Pin Score

requires user OAuth lazer

Pins a score to the user's profile.

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

const url = new URL( "https://osu.ppy.sh/api/v2/score-pins/18" ); const headers = { "Content-Type": "application/json", "Accept": "application/json", }; fetch(url, { method: "PUT", headers, }).then(response => response.json());

[Empty response] 

Request

PUT /score-pins/{score}

Response Format

empty response

Undocumented

POST api/v2/session/verify

requires user OAuth

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

const url = new URL( "https://osu.ppy.sh/api/v2/session/verify" ); const headers = { "Content-Type": "application/json", "Accept": "application/json", }; fetch(url, { method: "POST", headers, }).then(response => response.json());

Request

POST /session/verify

POST api/v2/session/verify/mail-fallback

requires user OAuth

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

const url = new URL( "https://osu.ppy.sh/api/v2/session/verify/mail-fallback" ); const headers = { "Content-Type": "application/json", "Accept": "application/json", }; fetch(url, { method: "POST", headers, }).then(response => response.json());

Request

POST /session/verify/mail-fallback

POST api/v2/session/verify/reissue

requires user OAuth

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

const url = new URL( "https://osu.ppy.sh/api/v2/session/verify/reissue" ); const headers = { "Content-Type": "application/json", "Accept": "application/json", }; fetch(url, { method: "POST", headers, }).then(response => response.json());

Request

POST /session/verify/reissue

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

requires user OAuth lazer

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

const url = new URL( "https://osu.ppy.sh/api/v2/beatmaps/nulla/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

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

requires user OAuth lazer

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

const url = new URL( "https://osu.ppy.sh/api/v2/beatmaps/saepe/solo/scores/quo" ); 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}

PUT api/v2/beatmaps/{beatmap}/tags/{tag}

requires user OAuth lazer

curl --request PUT \ "https://osu.ppy.sh/api/v2/beatmaps/ex/tags/dolores" \ --header "Content-Type: application/json" \ --header "Accept: application/json"

const url = new URL( "https://osu.ppy.sh/api/v2/beatmaps/ex/tags/dolores" ); const headers = { "Content-Type": "application/json", "Accept": "application/json", }; fetch(url, { method: "PUT", headers, }).then(response => response.json());

Request

PUT /beatmaps/{beatmap}/tags/{tag}

PATCH /beatmaps/{beatmap}/tags/{tag}

DELETE api/v2/beatmaps/{beatmap}/tags/{tag}

requires user OAuth lazer

curl --request DELETE \ "https://osu.ppy.sh/api/v2/beatmaps/recusandae/tags/placeat" \ --header "Content-Type: application/json" \ --header "Accept: application/json"

const url = new URL( "https://osu.ppy.sh/api/v2/beatmaps/recusandae/tags/placeat" ); const headers = { "Content-Type": "application/json", "Accept": "application/json", }; fetch(url, { method: "DELETE", headers, }).then(response => response.json());

Request

DELETE /beatmaps/{beatmap}/tags/{tag}

GET api/v2/beatmapsets/events

OAuth public

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

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

requires user OAuth lazer

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

const url = new URL( "https://osu.ppy.sh/api/v2/beatmapsets/aut/favourites" ); const headers = { "Content-Type": "application/json", "Accept": "application/json", }; fetch(url, { method: "POST", headers, }).then(response => response.json());

Request

POST /beatmapsets/{beatmapset}/favourites

GET api/v2/blocks

requires user OAuth lazer

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

const url = new URL( "https://osu.ppy.sh/api/v2/blocks" ); const headers = { "Content-Type": "application/json", "Accept": "application/json", }; fetch(url, { method: "GET", headers, }).then(response => response.json());

Request

GET /blocks

POST api/v2/blocks

requires user OAuth lazer

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

const url = new URL( "https://osu.ppy.sh/api/v2/blocks" ); const headers = { "Content-Type": "application/json", "Accept": "application/json", }; fetch(url, { method: "POST", headers, }).then(response => response.json());

Request

POST /blocks

DELETE api/v2/blocks/{block}

requires user OAuth lazer

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

const url = new URL( "https://osu.ppy.sh/api/v2/blocks/possimus" ); const headers = { "Content-Type": "application/json", "Accept": "application/json", }; fetch(url, { method: "DELETE", headers, }).then(response => response.json());

Request

DELETE /blocks/{block}

GET api/v2/chat/presence

requires user OAuth lazer

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

POST api/v2/reports

requires user OAuth lazer

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

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

requires user OAuth lazer

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

const url = new URL( "https://osu.ppy.sh/api/v2/rooms/tenetur/users/eum" ); const headers = { "Content-Type": "application/json", "Accept": "application/json", }; fetch(url, { method: "PUT", headers, }).then(response => response.json());

Request

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

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

requires user OAuth lazer

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

const url = new URL( "https://osu.ppy.sh/api/v2/rooms/in/users/vitae" ); const headers = { "Content-Type": "application/json", "Accept": "application/json", }; fetch(url, { method: "DELETE", headers, }).then(response => response.json());

Request

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

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

OAuth public

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

const url = new URL( "https://osu.ppy.sh/api/v2/rooms/dolores/leaderboard" ); const headers = { "Content-Type": "application/json", "Accept": "application/json", }; fetch(url, { method: "GET", headers, }).then(response => response.json());

Request

GET /rooms/{room}/leaderboard

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

OAuth public

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

const url = new URL( "https://osu.ppy.sh/api/v2/rooms/officia/events" ); const headers = { "Content-Type": "application/json", "Accept": "application/json", }; fetch(url, { method: "GET", headers, }).then(response => response.json());

Request

GET /rooms/{room}/events

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

requires user OAuth lazer

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

const url = new URL( "https://osu.ppy.sh/api/v2/rooms/a/playlist/qui/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

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

requires user OAuth lazer

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

const url = new URL( "https://osu.ppy.sh/api/v2/rooms/sunt/playlist/beatae/scores/architecto" ); 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}

POST api/v2/rooms

requires user OAuth lazer

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

GET api/v2/rooms/{room}

OAuth public

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

const url = new URL( "https://osu.ppy.sh/api/v2/rooms/quia" ); const headers = { "Content-Type": "application/json", "Accept": "application/json", }; fetch(url, { method: "GET", headers, }).then(response => response.json());

Request

GET /rooms/{room}

DELETE api/v2/rooms/{room}

requires user OAuth lazer

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

const url = new URL( "https://osu.ppy.sh/api/v2/rooms/dolor" ); const headers = { "Content-Type": "application/json", "Accept": "application/json", }; fetch(url, { method: "DELETE", headers, }).then(response => response.json());

Request

DELETE /rooms/{room}

GET api/v2/seasonal-backgrounds

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

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

OAuth public

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

const url = new URL( "https://osu.ppy.sh/api/v2/scores/nulla/download" ); const headers = { "Content-Type": "application/json", "Accept": "application/json", }; fetch(url, { method: "GET", headers, }).then(response => response.json());

Request

GET /scores/{score}/download

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

OAuth public

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

const url = new URL( "https://osu.ppy.sh/api/v2/scores/porro/harum/download" ); const headers = { "Content-Type": "application/json", "Accept": "application/json", }; fetch(url, { method: "GET", headers, }).then(response => response.json());

Request

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

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

OAuth public

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

const url = new URL( "https://osu.ppy.sh/api/v2/scores/nobis/quod" ); const headers = { "Content-Type": "application/json", "Accept": "application/json", }; fetch(url, { method: "GET", headers, }).then(response => response.json());

Request

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

GET api/v2/users/lookup

OAuth public

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

const url = new URL( "https://osu.ppy.sh/api/v2/users/lookup" ); const headers = { "Content-Type": "application/json", "Accept": "application/json", }; fetch(url, { method: "GET", headers, }).then(response => response.json());

Request

GET /users/lookup

GET api/v2/friends

requires user OAuth friends.read

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

POST api/v2/friends

requires user OAuth lazer

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

const url = new URL( "https://osu.ppy.sh/api/v2/friends" ); const headers = { "Content-Type": "application/json", "Accept": "application/json", }; fetch(url, { method: "POST", headers, }).then(response => response.json());

Request

POST /friends

DELETE api/v2/friends/{friend}

requires user OAuth lazer

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

const url = new URL( "https://osu.ppy.sh/api/v2/friends/cum" ); const headers = { "Content-Type": "application/json", "Accept": "application/json", }; fetch(url, { method: "DELETE", headers, }).then(response => response.json());

Request

DELETE /friends/{friend}

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

requires user OAuth lazer

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

GET api/v2/tags

OAuth public

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

const url = new URL( "https://osu.ppy.sh/api/v2/tags" ); const headers = { "Content-Type": "application/json", "Accept": "application/json", }; fetch(url, { method: "GET", headers, }).then(response => response.json());

Request

GET /tags

Users

Get User Kudosu

OAuth public

Returns kudosu history.

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

const url = new URL( "https://osu.ppy.sh/api/v2/users/1/kudosu" ); const params = { "limit": "20", "offset": "1", }; Object.keys(params) .forEach(key => url.searchParams.append(key, params[key])); const headers = { "Content-Type": "application/json", "Accept": "application/json", }; fetch(url, { method: "GET", headers, }).then(response => response.json());

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

Request

GET /users/{user}/kudosu

Response format

Array of KudosuHistory.

Get User Scores

OAuth public

This endpoint returns the scores of specified user.

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

const url = new URL( "https://osu.ppy.sh/api/v2/users/1/scores/best" ); const params = { "legacy_only": "0", "include_fails": "0", "mode": "osu", "limit": "9", "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());

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

Request

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

Response format

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

Get User Beatmaps

OAuth public

Returns the beatmaps of specified user.

curl --request GET \ --get "https://osu.ppy.sh/api/v2/users/1/beatmapsets/favourite?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/beatmapsets/favourite" ); 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());

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

Request

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

Response format

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

Get User Recent Activity

OAuth public

Returns recent activity.

curl --request GET \ --get "https://osu.ppy.sh/api/v2/users/1/recent_activity?limit=18&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": "18", "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());

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

Request

GET /users/{user}/recent_activity

Response format

Array of Event.

Search Beatmaps Passed

OAuth public

Searches for the Beatmaps a User has passed by Beatmapset.

curl --request GET \ --get "https://osu.ppy.sh/api/v2/users/20/beatmaps-passed?beatmapset_ids[]=1&beatmapset_ids[]=2" \ --header "Content-Type: application/json" \ --header "Accept: application/json"

const url = new URL( "https://osu.ppy.sh/api/v2/users/20/beatmaps-passed" ); const params = { "beatmapset_ids[0]": "1", "beatmapset_ids[1]": "2", }; 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 /users/{user}/beatmaps-passed

Response format

Returns the list of Beatmaps completed matching the criteria.

Get User

OAuth public

This endpoint returns the detail of specified user.

curl --request GET \ --get "https://osu.ppy.sh/api/v2/users/1/osu?key=qui" \ --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": "qui", }; 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 User object section" 

Request

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

Response format

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

• account_history
• active_tournament_banner
• badges
• beatmap_playcounts_count
• favourite_beatmapset_count
• follower_count
• graveyard_beatmapset_count
• groups
• loved_beatmapset_count
• mapping_follower_count
• monthly_playcounts
• page
• pending_beatmapset_count
• previous_usernames
• rank_highest
• rank_history
• ranked_beatmapset_count
• replays_watched_counts
• scores_best_count
• scores_first_count
• scores_recent_count
• statistics
• statistics.country_rank
• statistics.rank
• statistics.variants
• support_level
• user_achievements

Get Users

OAuth public

Returns list of users.

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

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

Request

GET /users

Response format

Get Own Data

requires user OAuth identify

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

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

 "See User object section" 

Request

GET /me/{mode?}

Response format

See Get User.

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

Wiki

Get Wiki Page

The wiki article or image data.

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}

Response Format

Returns WikiPage.

Using Chat

TODO: better title

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

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

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

Public channels and activity timeout

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

Private messages are not affected by this activity timeout.

Getting the user's channel list

TODO: update default parameter

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

Creating a channel

Make a request to the Create Channel endpoint.

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

Joining a channel

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

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

Leaving a channel

Make a request to the Leave Channel endpoint.

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

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

Sending messages

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

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

Getting info about a channel

Make a request to the Get Channel endpoint.

Getting channel message history

Make a request to the Get Channel Messages endpoint.

Websocket

Connection

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

// Requires nodejs with using ESM. // Browser WebSocket does not support header option. import WebSocket from 'ws'; const url = 'notification-endpoint'; const token = 'some-token'; const headers = { Authorization: `Bearer ${token}`}; const ws = new WebSocket(url, [], { headers }); ws.on('message', (buffer) => console.log(buffer.toString()));

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

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

See Websocket Events for the structure of websocket messages.

Websocket Events

Websocket events generally have the following standard format:

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

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.

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

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

Commands currently do not have any payload.

chat.start

Send to the websocket to start receiving chat messages.

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

chat.end

Send to the websocket to stop receiving chat messages.

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

Object Structures

Beatmap

Represent a beatmap.

Optional attributes:

Failtimes

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

BeatmapDifficultyAttributes

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

osu

taiko

BeatmapExtended

Represent a beatmap. This extends Beatmap with additional attributes.

Additional attributes:

BeatmapOwner

Users that are no longer visible will still appear as a BeatmapOwner but have the username set to [deleted user].

BeatmapPack

Represent a beatmap pack.

Optional Attributes

BeatmapPackType

Available beatmap pack types:

BeatmapPlaycount

Represent the playcount of a beatmap.

BeatmapScores

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

BeatmapUserScore

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

Beatmapset

Represents a beatmapset.

Those fields are optional.

Covers

Rank status

The possible values are denoted either as integer or string.

BeatmapsetDiscussion

Represents a Beatmapset modding discussion.

MessageType

BeatmapsetDiscussionPost

Represents a post in a BeatmapsetDiscussion.

BeatmapsetDiscussionVote

Represents a vote on a BeatmapsetDiscussion.

BeatmapsetExtended

Represents a beatmapset. This extends Beatmapset with additional attributes.

The following attributes are always included as well:

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

Optional Attributes

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

Versions

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

Optional Attributes

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

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.

Optional attributes:

ChannelType

For PMs, two factors are taken into account:

• Is either user blocking the other? If so, deny.
• Does the target only accept PMs from friends? Is the current user a friend? If not, deny.

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.

Optional attributes:

Comment

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

Represents a single comment.

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.

CommentSort

Available sort types are new, old, top.

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:

Otherwise if object has been deleted:

CurrentUserAttributes

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.

ChatChannelUserAttributes

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.

Additional objects

Beatmap

Beatmapset

User

Available Types

achievement

When user obtained an achievement.

beatmapPlaycount

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

beatmapsetApprove

When a beatmapset changes state.

beatmapsetDelete

When a beatmapset is deleted.

beatmapsetRevive

When a beatmapset in graveyard state is updated.

beatmapsetUpdate

When a beatmapset is updated.

beatmapsetUpload

When a new beatmapset is uploaded.

rank

When a user achieves a certain rank on a beatmap.

rankLost

When a user loses first place to another user.

userSupportAgain

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

userSupportFirst

When a user becomes a supporter for the first time.

userSupportGift

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

usernameChange

When a user changes their username.

Forum

Forum Post

Following fields are optional.

Forum Topic

Poll

PollOption

GithubUser

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

Group

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

Optional Attributes

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

Description

KudosuHistory

Giver

Post

Match

MatchEvent

Optional Attributes

MatchEventType

MatchGame

Mod

{ "acronym": "MU", "settings": { "inverse_muting": true, "mute_combo_count": 1, "affects_hit_sounds": false } }

Represents a single configured gameplay mod.

ModSetting

The names and types of values of possible settings depend on which mod they pertain to. You can find a list of possible mods, and possible settings for each mod, in mods.json.

MultiplayerScores

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

MultiplayerScoresAround

MultiplayerScoresCursor

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

MultiplayerScoresSort

Sort option for multiplayer scores index.

NewsPost

Optional Attributes

Navigation

Nomination

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.

Event Names

beatmapset_discussion_lock

Details object:

beatmapset_discussion_post_new

Details object:

beatmapset_discussion_unlock

Details object:

beatmapset_disqualify

Details object:

beatmapset_love

Details object: