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.

Changelog

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

Breaking Changes

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.

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:

User is redirected back to your site

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

Exchange this code for an access token:

Example request:

curl -X POST \
    "https://osu.ppy.sh/oauth/token" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{"client_id":1,"client_secret":"clientsecret","code":"receivedcode","grant_type":"authorization_code","redirect_uri":"http:\/\/localhost:4000"}'

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

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

let body = {
    "client_id": 1,
    "client_secret": "clientsecret",
    "code": "receivedcode",
    "grant_type": "authorization_code",
    "redirect_uri": "http:\/\/localhost:4000"
}

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

Example response (200):

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

Response Format

Successful requests will be issued an access token:

Client Credentials Grant

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

Example for requesting Client Credentials token:

Example request:

curl -X POST \
    "https://osu.ppy.sh/oauth/token" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{"client_id":1,"client_secret":"clientsecret","grant_type":"client_credentials","scope":"public"}'

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

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

let body = {
    "client_id": 1,
    "client_secret": "clientsecret",
    "grant_type": "client_credentials",
    "scope": "public"
}

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

Example response (200):

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

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

Returns beatmap.

OAuth public

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/beatmaps/lookup?checksum=et&filename=eum&id=sed" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

let params = {
    "checksum": "et",
    "filename": "eum",
    "id": "sed",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

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

Example response (200):

"See Beatmap object section"

Response format

See Get Beatmap

Get a User Beatmap score

Return a User's score on a Beatmap

OAuth public

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/beatmaps/3/scores/users/7?mode=vel&mods=pariatur" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

let params = {
    "mode": "vel",
    "mods": "pariatur",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

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

Response Format

Returns BeatmapUserScore

The position returned depends on the requested mode and mods.

Get a User Beatmap scores

Return a User's scores on a Beatmap

OAuth public

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/beatmaps/4/scores/users/10/all?mode=libero" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

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

Response Format

Get Beatmap scores

Returns the top scores for a beatmap

OAuth public

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/beatmaps/17/scores?mode=et&mods=rerum&type=id" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

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

Response Format

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

Get Beatmap scores (temp)

Returns the top scores for a beatmap from newer client.

This is a temporary endpoint.

OAuth public

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/beatmaps/5/solo-scores?mode=ipsum&mods=molestiae&type=nihil" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

let params = {
    "mode": "ipsum",
    "mods": "molestiae",
    "type": "nihil",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

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

Response Format

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

Get Beatmaps

Returns a list of beatmaps.

OAuth public

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/beatmaps?ids[]=1" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

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

Example response (200):

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

Response format

Get Beatmap

Gets beatmap data for the specified beatmap ID.

OAuth public

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/beatmaps/5" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

Example response (200):

"See Beatmap object section."

Response format

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

Get Beatmap Attributes

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

OAuth public

Example request:

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

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

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

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

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

Example response (200):

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

Response format

Beatmapset Discussions

Get Beatmapset Discussion Posts

Returns the posts of beatmapset discussions.

OAuth public

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/beatmapsets/discussions/posts?beatmapset_discussion_id=in&limit=12&page=15&sort=delectus&types[]=consequuntur&user=fugit&with_deleted=neque" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

let params = {
    "beatmapset_discussion_id": "in",
    "limit": "12",
    "page": "15",
    "sort": "delectus",
    "types[]": "consequuntur",
    "user": "fugit",
    "with_deleted": "neque",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

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

Response Format

Get Beatmapset Discussion Votes

Returns the votes given to beatmapset discussions.

OAuth public

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/beatmapsets/discussions/votes?beatmapset_discussion_id=et&limit=17&page=1&receiver=fugiat&score=voluptatem&sort=quidem&user=voluptas&with_deleted=minus" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

let params = {
    "beatmapset_discussion_id": "et",
    "limit": "17",
    "page": "1",
    "receiver": "fugiat",
    "score": "voluptatem",
    "sort": "quidem",
    "user": "voluptas",
    "with_deleted": "minus",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

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

Response Format

Get Beatmapset Discussions

Returns a list of beatmapset discussions.

OAuth public

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/beatmapsets/discussions?beatmap_id=veniam&beatmapset_id=eligendi&beatmapset_status=corrupti&limit=15&message_types[]=iste&only_unresolved=ab&page=11&sort=necessitatibus&user=eum&with_deleted=hic" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

let params = {
    "beatmap_id": "veniam",
    "beatmapset_id": "eligendi",
    "beatmapset_status": "corrupti",
    "limit": "15",
    "message_types[]": "iste",
    "only_unresolved": "ab",
    "page": "11",
    "sort": "necessitatibus",
    "user": "eum",
    "with_deleted": "hic",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

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

Response Format

Changelog

Get Changelog Build

Returns details of the specified build.

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/changelog/stable40/20210520.2" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

Example response (200):

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

Response Format

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

Get Changelog Listing

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

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/changelog?message_formats[]=veritatis" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

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

Example response (200):

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

Response Format

Lookup Changelog Build

Returns details of the specified build.

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/changelog/20210520.2?message_formats[]=ea" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

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

Example response (200):

See "Get Changelog Build" response.

Response Format

See Get Changelog Build.

Chat

/chat/ack

OAuth lazer

Example request:

curl -X POST \
    "https://osu.ppy.sh/api/v2/chat/ack" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

Create New PM

This endpoint allows you to create a new PM channel.

OAuth chat.write

Example request:

curl -X POST \
    "https://osu.ppy.sh/api/v2/chat/new" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{"target_id":3,"message":"harum","is_action":true,"uuid":"some-uuid-string"}'

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

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

let body = {
    "target_id": 3,
    "message": "harum",
    "is_action": true,
    "uuid": "some-uuid-string"
}

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

Example response (200):

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

Response Format

Get Updates

This endpoint returns new messages since the given message_id along with updated channel 'presence' data.

OAuth lazer

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/chat/updates?channel_id=9&history_since=19&includes[]=dolor&limit=15&since=3" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

let params = {
    "channel_id": "9",
    "history_since": "19",
    "includes[]": "dolor",
    "limit": "15",
    "since": "3",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

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

Example response (200):

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

Response Format

Get Channel Messages

This endpoint returns the chat messages for a specific channel.

OAuth lazer

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/chat/channels/9/messages?limit=11&since=13&until=6" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

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

Example response (200):

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

Response Format

Returns an array of ChatMessage

Send Message to Channel

This endpoint returns the chat messages for a specific channel.

OAuth lazer

Example request:

curl -X POST \
    "https://osu.ppy.sh/api/v2/chat/channels/14/messages" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{"message":"est","is_action":false}'

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

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

let body = {
    "message": "est",
    "is_action": false
}

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

Example response (200):

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

Response Format

The sent ChatMessage

Join Channel

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

OAuth lazer

Example request:

curl -X PUT \
    "https://osu.ppy.sh/api/v2/chat/channels/animi/users/voluptas" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

Example response (200):

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

Response Format

Returns the joined ChatChannel.

Leave Channel

This endpoint allows you to leave a public channel.

OAuth lazer

Example request:

curl -X DELETE \
    "https://osu.ppy.sh/api/v2/chat/channels/laudantium/users/nulla" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

Example response (204):

<Empty response>

Response Format

empty response

Mark Channel as Read

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

OAuth lazer

Example request:

curl -X PUT \
    "https://osu.ppy.sh/api/v2/chat/channels/ipsum/mark-as-read/odit?channel_id=sit&message_id=minima" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

let params = {
    "channel_id": "sit",
    "message_id": "minima",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

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

Example response (204):

<Empty response>

Response Format

empty response

Get Channel List

This endpoint returns a list of all joinable public channels.

OAuth lazer

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/chat/channels" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

Example response (200):

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

Response Format

Returns an array of ChatChannel

Create Channel

TODO: description needs fixing.

This endpoint creates a new channel if doesn't exist and joins it. Currently only for rejoining existing PM channels which the user has left.

OAuth chat.write

Example request:

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

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

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

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

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

Example response (200):

{
    "channel_id": 1,
    "name": "#pm_1-2",
    "description": "",
    "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
        }
    ]
}

Response Format

Returns ChatChannel with recent_messages attribute. Note that in the case of PMs, if there's no existing PM channel, most of the fields will be blank. In that case, send a message instead to create the channel.

Get Channel

Gets details of a chat channel.

OAuth lazer

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/chat/channels/sapiente" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

Example response (200):

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

Response Format

Comments

Get Comments

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

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/comments?commentable_type=quod&commentable_id=iusto&cursor=expedita&parent_id=nemo&sort=eius" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

let params = {
    "commentable_type": "quod",
    "commentable_id": "iusto",
    "cursor": "expedita",
    "parent_id": "nemo",
    "sort": "eius",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

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

Response Format

Returns CommentBundle.

pinned_comments is only included when commentable_type and commentable_id are specified.

Post a new comment

Posts a new comment to a comment thread.

OAuth lazer

Example request:

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

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

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

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

Response Format

Returns CommentBundle

Get a Comment

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

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/comments/rerum" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

Response Format

Returns CommentBundle

Edit Comment

Edit an existing comment.

OAuth lazer

Example request:

curl -X PUT \
    "https://osu.ppy.sh/api/v2/comments/quibusdam" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

Response Format

Returns CommentBundle

Delete Comment

Deletes the specified comment.

OAuth lazer

Example request:

curl -X DELETE \
    "https://osu.ppy.sh/api/v2/comments/et" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

Response Format

Returns CommentBundle

Add Comment vote

Upvotes a comment.

OAuth lazer

Example request:

curl -X POST \
    "https://osu.ppy.sh/api/v2/comments/recusandae/vote" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

Response Format

Returns CommentBundle

Remove Comment vote

Un-upvotes a comment.

OAuth lazer

Example request:

curl -X DELETE \
    "https://osu.ppy.sh/api/v2/comments/tempora/vote" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

Response Format

Returns CommentBundle

Forum

Reply Topic

Create a post replying to the specified topic.

OAuth forum.write

Example request:

curl -X POST \
    "https://osu.ppy.sh/api/v2/forums/topics/1/reply" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{"body":"hello"}'

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

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

Response Format

ForumPost with body included.

Create Topic

Create a new topic.

OAuth forum.write

Example request:

curl -X POST \
    "https://osu.ppy.sh/api/v2/forums/topics" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{"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"
);

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

Response Format

Get Topic and Posts

Get topic and its posts.

OAuth public

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/forums/topics/1" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

Example response (200):

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

Response Format

Edit Topic

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

OAuth forum.write

Example request:

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

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

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

Response Format

The edited ForumTopic.

Edit Post

Edit specified forum post.

OAuth forum.write

Example request:

curl -X PUT \
    "https://osu.ppy.sh/api/v2/forums/posts/1" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{"body":"hello"}'

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

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

Response Format

ForumPost with body included.

Home

Search

Searches users and wiki pages.

OAuth public

Example request:

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

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

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

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

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

Response Format

SearchResult<T>

Multiplayer

Get User High Score

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

OAuth lazer

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/rooms/7/playlist/13/scores/users/5" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

Response Format

Returns MultiplayerScore object.

Get Scores

Returns a list of scores for specified playlist item.

OAuth public

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/rooms/6/playlist/19/scores?limit=12&sort=illo&cursor=aut" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

let params = {
    "limit": "12",
    "sort": "illo",
    "cursor": "aut",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

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

Response Format

Returns MultiplayerScores object.

Get a Score

Returns detail of specified score and the surrounding scores.

OAuth lazer

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/rooms/2/playlist/19/scores/13" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

Response Format

Returns MultiplayerScore object.

News

Get News Listing

Returns a list of news posts and related metadata.

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/news" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

Example response (200):

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

Response Format

Get News Post

Returns details of the specified news post.

Example request:

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

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

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

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

Example response (200):

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

Response Format

Returns a NewsPost with content and navigation included.

Notification

Get Notifications

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

OAuth lazer

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/notifications?max_id=nam" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

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

Example response (200):

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

Response Format

Returns an object containing Notification and other related attributes.

Mark Notifications as Read

This endpoint allows you to mark notifications read.

OAuth lazer

Example request:

curl -X POST \
    "https://osu.ppy.sh/api/v2/notifications/mark-read" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{"ids":[1,2,3]}'

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

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

let body = {
    "ids": [
        1,
        2,
        3
    ]
}

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

Example response (204):

<Empty response>

Response Format

empty response

OAuth Tokens

Revoke current token

Revokes currently authenticated token.

OAuth

Example request:

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

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

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

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

Example response (204):

<Empty response>

Ranking

Get Ranking

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

OAuth public

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/rankings/mania/performance?country=0&filter=all&variant=4k" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

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

Response Format

Returns Rankings

Get Spotlights

Gets the list of spotlights.

OAuth public

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/spotlights" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

Response Format

Returns Spotlights

Undocumented

/beatmaps/{beatmap}/solo/scores

OAuth lazer

Example request:

curl -X POST \
    "https://osu.ppy.sh/api/v2/beatmaps/quasi/solo/scores" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

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

OAuth lazer

Example request:

curl -X PUT \
    "https://osu.ppy.sh/api/v2/beatmaps/aut/solo/scores/eos" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

/beatmapsets/events

OAuth public

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/beatmapsets/events" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

/beatmapsets/{beatmapset}/favourites

OAuth lazer

Example request:

curl -X POST \
    "https://osu.ppy.sh/api/v2/beatmapsets/rerum/favourites" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

/chat/presence

OAuth lazer

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/chat/presence" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

/matches

OAuth public

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/matches" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

/matches/{match}

OAuth public

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/matches/repellat" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

/rooms/{mode?}

OAuth public

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/rooms/repudiandae" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

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

OAuth lazer

Example request:

curl -X PUT \
    "https://osu.ppy.sh/api/v2/rooms/ex/users/vel" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

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

OAuth lazer

Example request:

curl -X DELETE \
    "https://osu.ppy.sh/api/v2/rooms/aliquid/users/maiores" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

/rooms/{room}/leaderboard

OAuth public

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/rooms/magnam/leaderboard" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

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

OAuth lazer

Example request:

curl -X POST \
    "https://osu.ppy.sh/api/v2/rooms/molestiae/playlist/rerum/scores" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

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

OAuth lazer

Example request:

curl -X PUT \
    "https://osu.ppy.sh/api/v2/rooms/sunt/playlist/sed/scores/facilis" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

/reports

OAuth lazer

Example request:

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

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

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

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

/rooms

OAuth lazer

Example request:

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

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

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

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

/rooms/{room}

OAuth public

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/rooms/ut" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

/seasonal-backgrounds

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/seasonal-backgrounds" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

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

OAuth public

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/scores/corrupti/voluptate/download" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

/scores/{mode}/{score}

OAuth public

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/scores/sit/tempora" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

/beatmapsets/search/{filters?}

OAuth public

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/beatmapsets/search/quo" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

/beatmapsets/lookup

OAuth public

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/beatmapsets/lookup" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

/beatmapsets/{beatmapset}

OAuth public

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/beatmapsets/aspernatur" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

/friends

OAuth friends.read

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/friends" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

/me/download-quota-check

OAuth lazer

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/me/download-quota-check" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

/beatmapsets/{beatmapset}/download

OAuth lazer

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/beatmapsets/repellat/download" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

Users

Get Own Data

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

OAuth identify

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/me/osu" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

Example response (200):

"See User object section"

Response format

See Get User.

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

Get User Kudosu

Returns kudosu history.

OAuth public

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/users/1/kudosu?limit=15&offset=1" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

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

Example response (200):

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

Response format

Array of KudosuHistory.

Get User Scores

This endpoint returns the scores of specified user.

OAuth public

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/users/1/scores/best?include_fails=0&mode=osu&limit=13&offset=1" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

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

Example response (200):

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

Response format

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

Get User Beatmaps

Returns the beatmaps of specified user.

OAuth public

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/users/1/beatmapsets/favourite?limit=14&offset=1" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

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

Example response (200):

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

Response format

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

Get User Recent Activity

Returns recent activity.

OAuth public

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/users/1/recent_activity?limit=7&offset=1" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

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

Example response (200):

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

Response format

Array of Event.

Get User

This endpoint returns the detail of specified user.

OAuth public

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/users/1/osu?key=illo" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

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

Example response (200):

"See User object section"

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

Returns list of users.

OAuth public

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/users?ids[]=1" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

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

Example response (200):

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

Response format

Wiki

Get Wiki Page

The wiki article or image data.

Example request:

curl -X GET \
    -G "https://osu.ppy.sh/api/v2/wiki/en/Welcome" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

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

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

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

Response Format

Returns WikiPage.

Notification Websocket

Connection

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

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

This endpoint allows you to receive notifications without constantly polling the server. Correct notification will be a JSON string with at least event field:

Events:

• logout: user session using same authentication key has been logged out (not yet implemented for OAuth authentication)
• new: new notification
• read: notification has been read

logout event

Server will disconnect session after sending this event so don't try to reconnect.

new event

New notification. See Notification object for notification types.

read event

Notification has been read.

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.

MessageType

BeatmapsetDiscussionPost

Represents a post in a BeatmapsetDiscussion.

BeatmapsetDiscussionVote

Represents a vote on a BeatmapsetDiscussion.

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.

Channel Types

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

{
  "message_id": 9150005004,
  "sender_id": 2,
  "channel_id": 5,
  "timestamp": "2018-07-06T06:33:34+00:00",
  "content": "i am a lazerface",
  "is_action": false,
  "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.

Comment

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

Represents an single comment.

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.

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 Post

Following fields are optional.

Forum Topic

Poll

PollOption

GameMode

Available game modes:

GithubUser

{
  "id": 218,
  "display_name": "bdach",
  "github_url": "https://github.com/bdach",
  "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

MultiplayerScore

Score data.

MultiplayerScores

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

To fetch the next page, make request to scores index with relevant room and playlist, with parameters which consists of:

• everything in params
• everything in cursor as sub field of cursor

For example, given a response which params contains

and cursor of

then the parameters would be

and thus the query string is sort=score_asc&limit=10&cursor[score_id]=1&cursor[total_score]=10.

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

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