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)
• rosu-v2 (rust)

Changelog

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

Breaking Changes

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(#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.

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

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

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

Response Format

Successful requests will be issued an access token:

Using the access token to access the API

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

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

Authorization: Bearer {{token}}

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

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

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

Resource Owner

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

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

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

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

Client Credentials Delegation

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

The following scopes currently support delegation:

Scopes

The following scopes are currently supported:

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

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

Using the chat.write scope requires either

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

Managing OAuth applications

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

Reset Client Secret

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

Beatmaps

Lookup Beatmap

OAuth public

Returns beatmap.

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

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

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

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

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

"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/1?mode=sit&mods=animi" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

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

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

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

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

Request

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

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/19/scores/users/17/all?mode=vitae" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

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

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

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

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

Request

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

Response Format

Get Beatmap scores

OAuth public

Returns the top scores for a beatmap

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

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

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

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

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

Request

GET /beatmaps/{beatmap}/scores

Response Format

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

Get Beatmap scores (temp)

OAuth public

Returns the top scores for a beatmap from newer client.

This is a temporary endpoint.

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

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

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

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

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

Request

GET /beatmaps/{beatmap}/solo-scores

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

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

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

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

"See Beatmap object section."
 

Request

GET /beatmaps/{beatmap}

Response format

Returns Beatmap 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=nostrum&limit=2&page=2&sort=nostrum&types%5B%5D=et&user=quas&with_deleted=vero" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

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

const params = {
    "beatmapset_discussion_id": "nostrum",
    "limit": "2",
    "page": "2",
    "sort": "nostrum",
    "types[]": "et",
    "user": "quas",
    "with_deleted": "vero",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

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

Request

GET /beatmapsets/discussions/posts

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=quo&limit=8&page=5&receiver=nesciunt&score=autem&sort=alias&user=veritatis&with_deleted=delectus" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

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

const params = {
    "beatmapset_discussion_id": "quo",
    "limit": "8",
    "page": "5",
    "receiver": "nesciunt",
    "score": "autem",
    "sort": "alias",
    "user": "veritatis",
    "with_deleted": "delectus",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

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

Request

GET /beatmapsets/discussions/votes

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=a&beatmapset_id=et&beatmapset_status=nesciunt&limit=6&message_types%5B%5D=suscipit&only_unresolved=dolores&page=20&sort=qui&user=veniam&with_deleted=aut" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

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

const params = {
    "beatmap_id": "a",
    "beatmapset_id": "et",
    "beatmapset_status": "nesciunt",
    "limit": "6",
    "message_types[]": "suscipit",
    "only_unresolved": "dolores",
    "page": "20",
    "sort": "qui",
    "user": "veniam",
    "with_deleted": "aut",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

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

Request

GET /beatmapsets/discussions

Response Format

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": {
                "id": null,
                "display_name": "peppy",
                "github_url": null,
                "osu_username": "peppy",
                "user_id": 2,
                "user_url": "https://osu.ppy.sh/users/2"
            }
        }
    ],
    "versions": {
        "previous": {
            "id": 5774,
            "version": "20210519.3",
            "display_version": "20210519.3",
            "users": 10,
            "created_at": "2021-05-19T11:51:48+00:00",
            "update_stream": {
                "id": 5,
                "name": "stable40",
                "display_name": "Stable",
                "is_featured": true
            }
        }
    }
}
 

Request

GET /changelog/{stream}/{build}

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

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

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

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

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

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

Request

GET /changelog

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

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

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

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

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

See "Get Changelog Build" response.
 

Request

GET /changelog/{changelog}

Response Format

See Get Changelog Build.

Chat

Chat Keepalive

requires user OAuth lazer

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

See Public channels and activity timeout

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

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

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

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

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

Request

POST /chat/ack

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\": 6,
    \"message\": \"quaerat\",
    \"is_action\": false,
    \"uuid\": \"some-uuid-string\"
}"

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

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

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

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

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

Request

POST /chat/new

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

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

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

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

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

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

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=7&since=10&until=11" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

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

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

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

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

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

This endpoint returns the chat messages for a specific channel.

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

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

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

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

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

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

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

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

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

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

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

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

This endpoint allows you to leave a public channel.

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

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

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

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

[Empty response]
 

Request

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

Response Format

empty response

Mark Channel as Read

requires user OAuth lazer

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

curl --request PUT \
    "https://osu.ppy.sh/api/v2/chat/channels/placeat/mark-as-read/quia?channel_id=asperiores&message_id=id" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

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

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

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

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

[Empty response]
 

Request

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

Response Format

empty response

Get Channel List

requires user OAuth lazer

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

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 lazer

Gets details of a chat channel.

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

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

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

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

{
    "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=sed&commentable_id=est&cursor=numquam&parent_id=nihil&sort=provident" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

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

const params = {
    "commentable_type": "sed",
    "commentable_id": "est",
    "cursor": "numquam",
    "parent_id": "nihil",
    "sort": "provident",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

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

Request

GET /comments

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

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

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

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

Request

GET /comments/{comment}

Response Format

Returns CommentBundle

Edit Comment

requires user OAuth lazer

Edit an existing comment.

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

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

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

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

Request

PUT /comments/{comment}

PATCH /comments/{comment}

Response Format

Returns CommentBundle

Delete Comment

requires user OAuth lazer

Deletes the specified comment.

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

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

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

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

Request

DELETE /comments/{comment}

Response Format

Returns CommentBundle

Add Comment vote

requires user OAuth lazer

Upvotes a comment.

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

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

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

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

Request

POST /comments/{comment}/vote

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

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

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

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

Request

DELETE /comments/{comment}/vote

Response Format

Returns CommentBundle

Forum

Reply Topic

requires user OAuth forum.write

Create a post replying to the specified topic.

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

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

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

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

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

Request

POST /forums/topics/{topic}/reply

Response Format

ForumPost with body included.

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.

Home

Search

OAuth public

Searches users and wiki pages.

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

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

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

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

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

Request

GET /search

Response Format

SearchResult<T>

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/2/scores/users/20" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

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

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

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

Request

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

Response Format

Returns MultiplayerScore object.

Get Scores

requires user OAuth public

Returns a list of scores for specified playlist item.

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

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

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

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

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

Request

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

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/16/playlist/7/scores/19" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

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

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

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

Request

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

Response Format

Returns MultiplayerScore object.

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

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

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

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

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

{
    "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 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/mania/performance?country=0&filter=all&variant=4k" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

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

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

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

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

Request

GET /rankings/{mode}/{type}

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

Undocumented

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

requires user OAuth lazer

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

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

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

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

Request

POST /beatmaps/{beatmap}/solo/scores

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

requires user OAuth lazer

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

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

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

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

Request

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

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

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

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

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

Request

POST /beatmapsets/{beatmapset}/favourites

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

GET api/v2/matches

OAuth public

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

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

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

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

Request

GET /matches

GET api/v2/matches/{match}

OAuth public

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

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

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

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

Request

GET /matches/{match}

GET api/v2/rooms/{mode?}

requires user OAuth public

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

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

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

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

Request

GET /rooms/{mode?}

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

requires user OAuth lazer

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

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

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

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

Request

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

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

requires user OAuth lazer

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

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

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

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

Request

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

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

requires user OAuth public

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

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

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

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

Request

GET /rooms/{room}/leaderboard

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

requires user OAuth lazer

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

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

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

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

Request

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

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

requires user OAuth lazer

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

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

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

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

Request

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

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

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

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

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

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

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

Request

GET /rooms/{room}

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

requires user OAuth public

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

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

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

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

Request

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

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

OAuth public

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

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

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

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

Request

GET /scores/{mode}/{score}

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

OAuth public

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

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

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

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

Request

GET /beatmapsets/search/{filters?}

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

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

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

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

Request

GET /beatmapsets/{beatmapset}

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

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

OAuth lazer

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

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

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

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

Request

GET /beatmapsets/{beatmapset}/download

Users

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.

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

Get User Kudosu

OAuth public

Returns kudosu history.

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

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

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

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

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

[
    {
        "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?include_fails=0&mode=osu&limit=2&offset=1" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

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

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

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

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

[
    {
        "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=3&offset=1" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

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

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

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

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

[
    {
        "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 Beatmapset, 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=11&offset=1" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

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

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

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

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

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

Request

GET /users/{user}/recent_activity

Response format

Array of Event.

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

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

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

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

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

"See User object section"
 

Request

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

Response format

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

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 when the over the websocket when the user joins a channel.

Leaving a channel

Make a request to the Leave Channel endpoint.

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

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

Sending messages

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

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

Getting info about a channel

Make a request to the Get Channel endpoint.

Getting channel message history

Make a request to the Get Channel Messages endpoint.

Websocket

Connection

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

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

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

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

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

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

See Websocket Events for the structure of websocket messages.

Websocket Events

Websocket events generally have the following standard format:

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

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.start' }));

Object Structures

Beatmap

Represent a beatmap. This extends BeatmapCompact with additional attributes.

Additional attributes:

BeatmapCompact

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

fruits

mania

BeatmapPlaycount

Represent the playcount of a beatmap.

BeatmapScores

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

BeatmapUserScore

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

Beatmapset

Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.

The following attributes are always included as well:

BeatmapsetCompact

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.