How to get osu api key
How to get osu api key
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-07-06
2022-06-08
2021-10-28
2021-09-01
2021-08-11
2021-06-14
2021-06-09
2021-04-20
2021-02-25
2020-09-08
2020-08-28
2020-05-01
2020-02-18
2019-10-09
2019-07-18
Endpoint
Base URL
The base URL is: https://osu.ppy.sh/api/[version]/
API Versions
This is combined with the base endpoint to determine where requests should be sent.
| Version | Status |
|---|---|
| v2 | current (not yet public, consider unstable and expect breaking changes) |
| v1 | legacy api provided by the old site, will be deprecated soon |
Authentication
Routes marked with the OAuth label require a valid OAuth2 token for access.
More information about applications you have registered and granted permissions to can be found here.
The API supports the following grant types:
Before you can use the osu!api, you will need to
Registering an OAuth application
Before you can get an OAuth token, you will need to register an OAuth application on your account settings page
To register an OAuth application you will need to provide the:
| Name | Description |
|---|---|
| Application Name | This is the name that will be visible to users of your application. The name of your application cannot be changed. |
| Application Callback URL | The URL in your application where users will be sent after authorization. |
The Application Callback URL is required when for using Authorization Codes. This may be left blank if you are only using Client Credentials Grants.
Your new OAuth application will have a Client ID and Client Secret ; the Client Secret is like a password for your OAuth application, it should be kept private and do not share it with anyone else.
Authorization Code Grant
The flow to authorize users for your application is:
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:
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:
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.
Make sure to replace <
> 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:
| Name | Description |
|---|---|
| chat.write | Allows sending chat messages on a user’s behalf. |
| delegate | Allows acting as the owner of a client; only available for Client Credentials Grant. |
| forum.write | Allows creating and editing forum posts on a user’s behalf. |
| friends.read | Allows reading of the user’s friend list. |
| identify | Allows reading of the public profile of the user ( /me ). |
| public | Allows reading of publicly available data on behalf of the user. |
identify is the default scope for the Authorization Code Grant and always implicitly provided. The Client Credentials Grant does not currently have any default scopes.
Routes marked with lazer are intended for use by the osu!lazer client and not currently available for use with Authorization Code or Client Credentials grants.
Using the chat.write scope requires either
Managing OAuth applications
Your account settings page will show your registered OAuth applications, and all the OAuth applications you have granted permissions to.
Reset Client Secret
You can generate a new Client Secret by choosing to «Reset client secret», however, this will disable all access tokens issued for the application.
Beatmaps
Lookup Beatmap
Response format
Get a User Beatmap score
Return a User’s score on a Beatmap
Response Format
The position returned depends on the requested mode and mods.
Get a User Beatmap scores
Return a User’s scores on a Beatmap
Response Format
Get Beatmap scores
Returns the top scores for a beatmap
Response Format
Get Beatmap scores (temp)
Returns the top scores for a beatmap from newer client.
This is a temporary endpoint.
Response Format
Get Beatmaps
Returns list of beatmaps.
Response format
| Field | Type | Description |
|---|---|---|
| beatmaps | BeatmapCompact[] | Includes: beatmapset (with ratings), failtimes, max_combo. |
Get Beatmap
Gets beatmap data for the specified beatmap ID.
Response format
Returns Beatmap object. Following attributes are included in the response object when applicable,
| Attribute | Notes |
|---|---|
| beatmapset | Includes ratings property. |
| failtimes | |
| max_combo |
Get Beatmap Attributes
Returns difficulty attributes of beatmap with specific mode and mods combination.
Response format
Beatmapset Discussions
Get Beatmapset Discussion Posts
Returns the posts of beatmapset discussions.
Response Format
Get Beatmapset Discussion Votes
Returns the votes given to beatmapset discussions.
Response Format
Get Beatmapset Discussions
Returns a list of beatmapset discussions.
Response Format
Changelog
Get Changelog Build
Returns details of the specified build.
Response Format
Get Changelog Listing
Returns a listing of update streams, builds, and changelog entries.
Response Format
Lookup Changelog Build
Returns details of the specified build.
Response Format
Create New PM
This endpoint allows you to create a new PM channel.
Response Format
| Field | Type |
|---|---|
| new_channel_id | channel_id of newly created ChatChannel |
| presence | array of ChatChannel |
| message | the sent ChatMessage |
This endpoint will only allow the creation of PMs initially, group chat support will come later.
Get Updates
This endpoint returns new messages since the given message_id along with updated channel ‘presence’ data.
Response Format
Get Channel Messages
This endpoint returns the chat messages for a specific channel.
Response Format
Returns an array of ChatMessage
Send Message to Channel
This endpoint returns the chat messages for a specific channel.
Response Format
Join Channel
This endpoint allows you to join a public or multiplayer channel.
Response Format
Returns the joined ChatChannel.
Leave Channel
This endpoint allows you to leave a public channel.
Response Format
Mark Channel as Read
Response Format
Get Channel List
This endpoint returns a list of all joinable public channels.
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.
Response Format
Returns ChatChannel with recent_messages attribute. Note that in the case of PM s, 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.
Response Format
| Field | Type | Description |
|---|---|---|
| channel | ChatChannel | |
| users | UserCompact | Users are only visible for PM channels. |
Comments
Get Comments
Returns a list comments and their replies up to 2 levels deep.
Response Format
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.
Response Format
Get a Comment
Gets a comment and its replies up to 2 levels deep.
Response Format
Edit Comment
Edit an existing comment.
Response Format
Delete Comment
Deletes the specified comment.
Response Format
Add Comment vote
Upvotes a comment.
Response Format
Remove Comment vote
Un-upvotes a comment.
Response Format
Forum
Reply Topic
Create a post replying to the specified topic.
Response Format
ForumPost with body included.
Create Topic
Create a new topic.
Response Format
Get Topic and Posts
Get topic and its posts.
Response Format
Edit Topic
Edit topic. Only title can be edited through this endpoint.
Response Format
Edit Post
Edit specified forum post.
Response Format
ForumPost with body included.
Search
Searches users and wiki pages.
Response Format
SearchResult
Multiplayer
Get User High Score
Returns detail of highest score of specified user and the surrounding scores.
Response Format
Get Scores
Returns a list of scores for specified playlist item.
Response Format
Get a Score
Returns detail of specified score and the surrounding scores.
Response Format
Get News Listing
Returns a list of news posts and related metadata.
Response Format
Get News Post
Returns details of the specified news post.
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.
Response Format
Returns an object containing Notification and other related attributes.
| Field | Type |
|---|---|
| has_more | boolean whether or not there are more notifications |
| notifications | array of Notification |
| unread_count | total unread notifications |
| notification_endpoint | url to connect to websocket server |
Mark Notifications as Read
This endpoint allows you to mark notifications read.
Response Format
OAuth Tokens
Revoke current token
Revokes currently authenticated token.
Ranking
Get Ranking
Gets the current ranking for the specified type and game mode.
Response Format
Get Spotlights
Gets the list of spotlights.
Response Format
Undocumented
/beatmaps//solo/scores
/beatmaps//solo/scores//beatmapsets/events
/beatmapsets//favourites
/chat/presence
/matches
/matches//rooms//rooms//users//rooms//users//rooms//leaderboard
/rooms//playlist//scores
/rooms//playlist//scores//reports
/rooms
/rooms//seasonal-backgrounds
/scores///download
/scores///beatmapsets/search//beatmapsets/lookup
/beatmapsets//friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
Similar to Get User but with authenticated user (token owner) as user id.
Response format
Additionally, statistics_rulesets is included, containing statistics for all rulesets.
Get User Kudosu
Returns kudosu history.
Response format
Get User Scores
This endpoint returns the scores of specified user.
Response format
Array of Score. Following attributes are included in the response object when applicable.
Get User Beatmaps
Returns the beatmaps of specified user.
Type Notes favourite graveyard loved most_played pending Previously unranked ranked Previously ranked_and_approved
Response format
Array of BeatmapPlaycount when type is most_played ; array of Beatmapset, otherwise.
Get User Recent Activity
Returns recent activity.
Response format
Get User
This endpoint returns the detail of specified user.
Response format
Returns User object. The following optional attributes on UserCompact are included:
Get Users
Returns list of users.
Response format
Field Type Description users UserCompact[] Includes: country, cover, groups, statistics_rulesets.
Get Wiki Page
The wiki article or image data.
Response Format
Notification Websocket
Connection
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:
Field Type Description event string See below
logout event
Server will disconnect session after sending this event so don’t try to reconnect.
Field Type Description event string logout
new event
New notification. See Notification object for notification types.
Field Type Description event string new data Notification
read event
Notification has been read.
Field Type Description event string read ids number[] id of Notifications which are read
Object Structures
Beatmap
Represent a beatmap. This extends BeatmapCompact with additional attributes.
Field Type Description accuracy float ar float beatmapset_id integer bpm float? convert boolean count_circles integer count_sliders integer count_spinners integer cs float deleted_at Timestamp? drain float hit_length integer is_scoreable boolean last_updated Timestamp mode_int integer passcount integer playcount integer ranked integer See Rank status for list of possible values. url string
BeatmapCompact
Represent a beatmap.
Field Type Description beatmapset_id integer difficulty_rating float id integer mode GameMode status string See Rank status for list of possible values. total_length integer user_id integer version string
Field Type Description beatmapset Beatmapset|BeatmapsetCompact|null Beatmapset for Beatmap object, BeatmapsetCompact for BeatmapCompact object. null if the beatmap doesn’t have associated beatmapset (e.g. deleted). checksum string? failtimes Failtimes max_combo integer
Failtimes
All fields are optional but there’s always at least one field returned.
Field Type Description exit integer[]? Array of length 100. fail integer[]? Array of length 100.
BeatmapDifficultyAttributes
Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.
Field Type max_combo integer star_rating float
Field Type aim_difficulty float approach_rate float flashlight_difficulty float overall_difficulty float slider_factor float speed_difficulty float
taiko
Field Type stamina_difficulty float rhythm_difficulty float colour_difficulty float approach_rate float great_hit_window float
fruits
mania
Field Type great_hit_window float score_multiplier float
BeatmapPlaycount
Represent the playcount of a beatmap.
Field Type Description beatmap_id number beatmap BeatmapCompact? beatmapset BeatmapsetCompact? count number
BeatmapScores
Field Type Description scores Score[] The list of top scores for the beatmap in descending order. userScore BeatmapUserScore? The score of the current user. This is not returned if the current user does not have a score. Note: will be moved to user_score in the future
BeatmapUserScore
Field Type Description position number The position of the score within the requested beatmap ranking. score Score The details of the score.
Beatmapset
Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.
Field Type Description availability.download_disabled boolean availability.more_information string? bpm float can_be_hyped boolean creator string Username of the mapper at the time of beatmapset creation. discussion_locked boolean hype.current integer hype.required integer is_scoreable boolean last_updated Timestamp legacy_thread_url string? nominations.current integer nominations.required integer ranked integer See Rank status for list of possible values. ranked_date Timestamp? source string storyboard boolean submitted_date Timestamp? tags string
The following attributes are always included as well:
Field has_favourited
BeatmapsetCompact
Represents a beatmapset.
Field Type Description artist string artist_unicode string covers Covers creator string favourite_count number id number nsfw boolean play_count number preview_url string source string status string title string title_unicode string user_id number video boolean
Those fields are optional.
Field Type Description beatmaps Beatmap[] converts current_user_attributes description discussions events genre has_favourited boolean language nominations ratings recent_favourites related_users user
Covers
Field Type cover string cover@2x string card string card@2x string list string list@2x string slimcover string slimcover@2x string
Rank status
The possible values are denoted either as integer or string.
Integer String -2 graveyard -1 wip 0 pending 1 ranked 2 approved 3 qualified 4 loved
BeatmapsetDiscussion
Represents a Beatmapset modding discussion.
Field Type Description beatmap BeatmapCompact? beatmap_id number? beatmapset BeatmapsetCompact? beatmapset_id number can_be_resolved boolean can_grant_kudosu boolean created_at Timestamp current_user_attributes CurrentUserAttributes deleted_at Timestamp? deleted_by_id number? id number kudosu_denied boolean last_post_at Timestamp message_type MessageType parent_id number? posts BeatmapsetDiscussionPost[]? resolved boolean starting_post BeatmapsetDiscussionPost? timestamp number? updated_at Timestamp user_id number
MessageType
Name Description hype mapper_note praise problem review suggestion
BeatmapsetDiscussionPost
Field Type Description beatmapset_discussion_id number created_at Timestamp deleted_at Timestamp? deleted_by_id number? id number last_editor_id number? message string system boolean updated_at Timestamp user_id number
BeatmapsetDiscussionVote
Field Type Description beatmapset_discussion_id number created_at Timestamp id number score number updated_at Timestamp user_id number
Build
Field Type created_at Timestamp display_version string id number update_stream UpdateStream? users number version string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes changelog_entries ChangelogEntry[] If the build has no changelog entries, a placeholder is generated. versions Versions
Versions
ChangelogEntry
Field Type category string created_at Timestamp? github_pull_request_id number? github_url string? id number? major boolean repository string? title string? type string url string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes github_user GithubUser If the changelog entry has no GitHub user, a placeholder is generated. message string? Entry message in Markdown format. Embedded HTML is allowed. message_html string? Entry message in HTML format.
ChatChannel
Represents an individual chat «channel» in the game.
Channel Types
Type Permission Check for Joining/Messaging PUBLIC PRIVATE is player in the allowed groups? (channel.allowed_groups) MULTIPLAYER is player currently in the mp game? SPECTATOR TEMPORARY deprecated PM see below (user_channels) GROUP is player in channel? (user_channels)
For PMs, two factors are taken into account:
ChatMessage
Represents an individual Message within a ChatChannel.
Field Type Description message_id number unique identifier for message sender_id number user_id of the sender channel_id number channel_id of where the message was sent timestamp string when the message was sent, ISO-8601 content string message content is_action boolean was this an action? i.e. /me dances sender UserCompact embedded UserCompact object to save additional api lookups
Comment
Represents an single comment.
Field Type Description commentable_id number ID of the object the comment is attached to commentable_type string type of object the comment is attached to created_at string ISO 8601 date deleted_at string? ISO 8601 date if the comment was deleted; null, otherwise edited_at string? ISO 8601 date if the comment was edited; null, otherwise edited_by_id number? user id of the user that edited the post; null, otherwise id number the ID of the comment legacy_name string? username displayed on legacy comments message string? markdown of the comment’s content message_html string? html version of the comment’s content parent_id number? ID of the comment’s parent pinned boolean Pin status of the comment replies_count number number of replies to the comment updated_at string ISO 8601 date user_id number user ID of the poster votes_count number number of votes
CommentBundle
Comments and related data.
Field Type Description commentable_meta CommentableMeta[] ID of the object the comment is attached to comments Comment[] Array of comments ordered according to sort ; cursor Cursor has_more boolean If there are more comments or replies available has_more_id number? included_comments Comment[] Related comments; e.g. parent comments and nested replies pinned_comments Comment[]? Pinned comments sort string one of the CommentSort types top_level_count number? Number of comments at the top level. Not returned for replies. total number? Total number of comments. Not retuned for replies. user_follow boolean is the current user watching the comment thread? user_votes number[] IDs of the comments in the bundle the current user has upvoted users UserCompact[] array of users related to the comments
CommentSort
Type Sort Fields new created_at (descending), id (descending) old created_at (ascending), id (ascending) top votes_count (descending), created_at (descending), id (descending)
Building cursor for comments listing
The returned response will be for comments after the specified sort fields.
For example, use last loaded comment for the fields value to load more comments. Also make sure to use same sort and parent_id values.
CommentableMeta
Metadata of the object that a comment is attached to.
Field Type Description id number the ID of the object title string display title type string the type of the object url string url of the object
CurrentUserAttributes
An object listing various related permissions and states for the current user, related to the object it is attached to.
BeatmapsetDiscussionPermissions
TODO: needs a better name.
Name Description can_destroy Can delete the discussion. can_reopen Can reopen the discussion. can_moderate_kudosu Can allow or deny kudosu. can_resolve Can resolve the discussion. vote_score Current vote given to the discussion.
ChatChannelUserAttributes
Name Type Description can_message boolean Can send messages to this channel. can_message_error string? Reason messages cannot be sent to this channel last_read_id number message_id of last message read.
Cursor
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.
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
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-07-06
2022-06-08
2021-10-28
2021-09-01
2021-08-11
2021-06-14
2021-06-09
2021-04-20
2021-02-25
2020-09-08
2020-08-28
2020-05-01
2020-02-18
2019-10-09
2019-07-18
Endpoint
Base URL
The base URL is: https://osu.ppy.sh/api/[version]/
API Versions
This is combined with the base endpoint to determine where requests should be sent.
Version Status v2 current (not yet public, consider unstable and expect breaking changes) v1 legacy api provided by the old site, will be deprecated soon
Authentication
Routes marked with the OAuth label require a valid OAuth2 token for access.
More information about applications you have registered and granted permissions to can be found here.
The API supports the following grant types:
Before you can use the osu!api, you will need to
Registering an OAuth application
Before you can get an OAuth token, you will need to register an OAuth application on your account settings page
To register an OAuth application you will need to provide the:
Name Description Application Name This is the name that will be visible to users of your application. The name of your application cannot be changed. Application Callback URL The URL in your application where users will be sent after authorization.
The Application Callback URL is required when for using Authorization Codes. This may be left blank if you are only using Client Credentials Grants.
Your new OAuth application will have a Client ID and Client Secret ; the Client Secret is like a password for your OAuth application, it should be kept private and do not share it with anyone else.
Authorization Code Grant
The flow to authorize users for your application is:
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:
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:
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.
Make sure to replace <> 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:
Name Description chat.write Allows sending chat messages on a user’s behalf. delegate Allows acting as the owner of a client; only available for Client Credentials Grant. forum.write Allows creating and editing forum posts on a user’s behalf. friends.read Allows reading of the user’s friend list. identify Allows reading of the public profile of the user ( /me ). public Allows reading of publicly available data on behalf of the user.
identify is the default scope for the Authorization Code Grant and always implicitly provided. The Client Credentials Grant does not currently have any default scopes.
Routes marked with lazer are intended for use by the osu!lazer client and not currently available for use with Authorization Code or Client Credentials grants.
Using the chat.write scope requires either
Managing OAuth applications
Your account settings page will show your registered OAuth applications, and all the OAuth applications you have granted permissions to.
Reset Client Secret
You can generate a new Client Secret by choosing to «Reset client secret», however, this will disable all access tokens issued for the application.
Beatmaps
Lookup Beatmap
Response format
Get a User Beatmap score
Return a User’s score on a Beatmap
Response Format
The position returned depends on the requested mode and mods.
Get a User Beatmap scores
Return a User’s scores on a Beatmap
Response Format
Get Beatmap scores
Returns the top scores for a beatmap
Response Format
Get Beatmap scores (temp)
Returns the top scores for a beatmap from newer client.
This is a temporary endpoint.
Response Format
Get Beatmaps
Returns list of beatmaps.
Response format
Field Type Description beatmaps BeatmapCompact[] Includes: beatmapset (with ratings), failtimes, max_combo.
Get Beatmap
Gets beatmap data for the specified beatmap ID.
Response format
Returns Beatmap object. Following attributes are included in the response object when applicable,
Attribute Notes beatmapset Includes ratings property. failtimes max_combo
Get Beatmap Attributes
Returns difficulty attributes of beatmap with specific mode and mods combination.
Response format
Beatmapset Discussions
Get Beatmapset Discussion Posts
Returns the posts of beatmapset discussions.
Response Format
Get Beatmapset Discussion Votes
Returns the votes given to beatmapset discussions.
Response Format
Get Beatmapset Discussions
Returns a list of beatmapset discussions.
Response Format
Changelog
Get Changelog Build
Returns details of the specified build.
Response Format
Get Changelog Listing
Returns a listing of update streams, builds, and changelog entries.
Response Format
Lookup Changelog Build
Returns details of the specified build.
Response Format
Create New PM
This endpoint allows you to create a new PM channel.
Response Format
Field Type new_channel_id channel_id of newly created ChatChannel presence array of ChatChannel message the sent ChatMessage
This endpoint will only allow the creation of PMs initially, group chat support will come later.
Get Updates
This endpoint returns new messages since the given message_id along with updated channel ‘presence’ data.
Response Format
Get Channel Messages
This endpoint returns the chat messages for a specific channel.
Response Format
Returns an array of ChatMessage
Send Message to Channel
This endpoint returns the chat messages for a specific channel.
Response Format
Join Channel
This endpoint allows you to join a public or multiplayer channel.
Response Format
Returns the joined ChatChannel.
Leave Channel
This endpoint allows you to leave a public channel.
Response Format
Mark Channel as Read
Response Format
Get Channel List
This endpoint returns a list of all joinable public channels.
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.
Response Format
Returns ChatChannel with recent_messages attribute. Note that in the case of PM s, 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.
Response Format
Field Type Description channel ChatChannel users UserCompact Users are only visible for PM channels.
Comments
Get Comments
Returns a list comments and their replies up to 2 levels deep.
Response Format
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.
Response Format
Get a Comment
Gets a comment and its replies up to 2 levels deep.
Response Format
Edit Comment
Edit an existing comment.
Response Format
Delete Comment
Deletes the specified comment.
Response Format
Add Comment vote
Upvotes a comment.
Response Format
Remove Comment vote
Un-upvotes a comment.
Response Format
Forum
Reply Topic
Create a post replying to the specified topic.
Response Format
ForumPost with body included.
Create Topic
Create a new topic.
Response Format
Get Topic and Posts
Get topic and its posts.
Response Format
Edit Topic
Edit topic. Only title can be edited through this endpoint.
Response Format
Edit Post
Edit specified forum post.
Response Format
ForumPost with body included.
Search
Searches users and wiki pages.
Response Format
SearchResult
Multiplayer
Get User High Score
Returns detail of highest score of specified user and the surrounding scores.
Response Format
Get Scores
Returns a list of scores for specified playlist item.
Response Format
Get a Score
Returns detail of specified score and the surrounding scores.
Response Format
Get News Listing
Returns a list of news posts and related metadata.
Response Format
Get News Post
Returns details of the specified news post.
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.
Response Format
Returns an object containing Notification and other related attributes.
Field Type has_more boolean whether or not there are more notifications notifications array of Notification unread_count total unread notifications notification_endpoint url to connect to websocket server
Mark Notifications as Read
This endpoint allows you to mark notifications read.
Response Format
OAuth Tokens
Revoke current token
Revokes currently authenticated token.
Ranking
Get Ranking
Gets the current ranking for the specified type and game mode.
Response Format
Get Spotlights
Gets the list of spotlights.
Response Format
Undocumented
/beatmaps//solo/scores
/beatmaps//solo/scores//beatmapsets/events
/beatmapsets//favourites
/chat/presence
/matches
/matches//rooms//rooms//users//rooms//users//rooms//leaderboard
/rooms//playlist//scores
/rooms//playlist//scores//reports
/rooms
/rooms//seasonal-backgrounds
/scores///download
/scores///beatmapsets/search//beatmapsets/lookup
/beatmapsets//friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
Similar to Get User but with authenticated user (token owner) as user id.
Response format
Additionally, statistics_rulesets is included, containing statistics for all rulesets.
Get User Kudosu
Returns kudosu history.
Response format
Get User Scores
This endpoint returns the scores of specified user.
Response format
Array of Score. Following attributes are included in the response object when applicable.
Get User Beatmaps
Returns the beatmaps of specified user.
Type Notes favourite graveyard loved most_played pending Previously unranked ranked Previously ranked_and_approved
Response format
Array of BeatmapPlaycount when type is most_played ; array of Beatmapset, otherwise.
Get User Recent Activity
Returns recent activity.
Response format
Get User
This endpoint returns the detail of specified user.
Response format
Returns User object. The following optional attributes on UserCompact are included:
Get Users
Returns list of users.
Response format
Field Type Description users UserCompact[] Includes: country, cover, groups, statistics_rulesets.
Get Wiki Page
The wiki article or image data.
Response Format
Notification Websocket
Connection
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:
Field Type Description event string See below
logout event
Server will disconnect session after sending this event so don’t try to reconnect.
Field Type Description event string logout
new event
New notification. See Notification object for notification types.
Field Type Description event string new data Notification
read event
Notification has been read.
Field Type Description event string read ids number[] id of Notifications which are read
Object Structures
Beatmap
Represent a beatmap. This extends BeatmapCompact with additional attributes.
Field Type Description accuracy float ar float beatmapset_id integer bpm float? convert boolean count_circles integer count_sliders integer count_spinners integer cs float deleted_at Timestamp? drain float hit_length integer is_scoreable boolean last_updated Timestamp mode_int integer passcount integer playcount integer ranked integer See Rank status for list of possible values. url string
BeatmapCompact
Represent a beatmap.
Field Type Description beatmapset_id integer difficulty_rating float id integer mode GameMode status string See Rank status for list of possible values. total_length integer user_id integer version string
Field Type Description beatmapset Beatmapset|BeatmapsetCompact|null Beatmapset for Beatmap object, BeatmapsetCompact for BeatmapCompact object. null if the beatmap doesn’t have associated beatmapset (e.g. deleted). checksum string? failtimes Failtimes max_combo integer
Failtimes
All fields are optional but there’s always at least one field returned.
Field Type Description exit integer[]? Array of length 100. fail integer[]? Array of length 100.
BeatmapDifficultyAttributes
Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.
Field Type max_combo integer star_rating float
Field Type aim_difficulty float approach_rate float flashlight_difficulty float overall_difficulty float slider_factor float speed_difficulty float
taiko
Field Type stamina_difficulty float rhythm_difficulty float colour_difficulty float approach_rate float great_hit_window float
fruits
mania
Field Type great_hit_window float score_multiplier float
BeatmapPlaycount
Represent the playcount of a beatmap.
Field Type Description beatmap_id number beatmap BeatmapCompact? beatmapset BeatmapsetCompact? count number
BeatmapScores
Field Type Description scores Score[] The list of top scores for the beatmap in descending order. userScore BeatmapUserScore? The score of the current user. This is not returned if the current user does not have a score. Note: will be moved to user_score in the future
BeatmapUserScore
Field Type Description position number The position of the score within the requested beatmap ranking. score Score The details of the score.
Beatmapset
Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.
Field Type Description availability.download_disabled boolean availability.more_information string? bpm float can_be_hyped boolean creator string Username of the mapper at the time of beatmapset creation. discussion_locked boolean hype.current integer hype.required integer is_scoreable boolean last_updated Timestamp legacy_thread_url string? nominations.current integer nominations.required integer ranked integer See Rank status for list of possible values. ranked_date Timestamp? source string storyboard boolean submitted_date Timestamp? tags string
The following attributes are always included as well:
Field has_favourited
BeatmapsetCompact
Represents a beatmapset.
Field Type Description artist string artist_unicode string covers Covers creator string favourite_count number id number nsfw boolean play_count number preview_url string source string status string title string title_unicode string user_id number video boolean
Those fields are optional.
Field Type Description beatmaps Beatmap[] converts current_user_attributes description discussions events genre has_favourited boolean language nominations ratings recent_favourites related_users user
Covers
Field Type cover string cover@2x string card string card@2x string list string list@2x string slimcover string slimcover@2x string
Rank status
The possible values are denoted either as integer or string.
Integer String -2 graveyard -1 wip 0 pending 1 ranked 2 approved 3 qualified 4 loved
BeatmapsetDiscussion
Represents a Beatmapset modding discussion.
Field Type Description beatmap BeatmapCompact? beatmap_id number? beatmapset BeatmapsetCompact? beatmapset_id number can_be_resolved boolean can_grant_kudosu boolean created_at Timestamp current_user_attributes CurrentUserAttributes deleted_at Timestamp? deleted_by_id number? id number kudosu_denied boolean last_post_at Timestamp message_type MessageType parent_id number? posts BeatmapsetDiscussionPost[]? resolved boolean starting_post BeatmapsetDiscussionPost? timestamp number? updated_at Timestamp user_id number
MessageType
Name Description hype mapper_note praise problem review suggestion
BeatmapsetDiscussionPost
Field Type Description beatmapset_discussion_id number created_at Timestamp deleted_at Timestamp? deleted_by_id number? id number last_editor_id number? message string system boolean updated_at Timestamp user_id number
BeatmapsetDiscussionVote
Field Type Description beatmapset_discussion_id number created_at Timestamp id number score number updated_at Timestamp user_id number
Build
Field Type created_at Timestamp display_version string id number update_stream UpdateStream? users number version string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes changelog_entries ChangelogEntry[] If the build has no changelog entries, a placeholder is generated. versions Versions
Versions
ChangelogEntry
Field Type category string created_at Timestamp? github_pull_request_id number? github_url string? id number? major boolean repository string? title string? type string url string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes github_user GithubUser If the changelog entry has no GitHub user, a placeholder is generated. message string? Entry message in Markdown format. Embedded HTML is allowed. message_html string? Entry message in HTML format.
ChatChannel
Represents an individual chat «channel» in the game.
Channel Types
Type Permission Check for Joining/Messaging PUBLIC PRIVATE is player in the allowed groups? (channel.allowed_groups) MULTIPLAYER is player currently in the mp game? SPECTATOR TEMPORARY deprecated PM see below (user_channels) GROUP is player in channel? (user_channels)
For PMs, two factors are taken into account:
ChatMessage
Represents an individual Message within a ChatChannel.
Field Type Description message_id number unique identifier for message sender_id number user_id of the sender channel_id number channel_id of where the message was sent timestamp string when the message was sent, ISO-8601 content string message content is_action boolean was this an action? i.e. /me dances sender UserCompact embedded UserCompact object to save additional api lookups
Comment
Represents an single comment.
Field Type Description commentable_id number ID of the object the comment is attached to commentable_type string type of object the comment is attached to created_at string ISO 8601 date deleted_at string? ISO 8601 date if the comment was deleted; null, otherwise edited_at string? ISO 8601 date if the comment was edited; null, otherwise edited_by_id number? user id of the user that edited the post; null, otherwise id number the ID of the comment legacy_name string? username displayed on legacy comments message string? markdown of the comment’s content message_html string? html version of the comment’s content parent_id number? ID of the comment’s parent pinned boolean Pin status of the comment replies_count number number of replies to the comment updated_at string ISO 8601 date user_id number user ID of the poster votes_count number number of votes
CommentBundle
Comments and related data.
Field Type Description commentable_meta CommentableMeta[] ID of the object the comment is attached to comments Comment[] Array of comments ordered according to sort ; cursor Cursor has_more boolean If there are more comments or replies available has_more_id number? included_comments Comment[] Related comments; e.g. parent comments and nested replies pinned_comments Comment[]? Pinned comments sort string one of the CommentSort types top_level_count number? Number of comments at the top level. Not returned for replies. total number? Total number of comments. Not retuned for replies. user_follow boolean is the current user watching the comment thread? user_votes number[] IDs of the comments in the bundle the current user has upvoted users UserCompact[] array of users related to the comments
CommentSort
Type Sort Fields new created_at (descending), id (descending) old created_at (ascending), id (ascending) top votes_count (descending), created_at (descending), id (descending)
Building cursor for comments listing
The returned response will be for comments after the specified sort fields.
For example, use last loaded comment for the fields value to load more comments. Also make sure to use same sort and parent_id values.
CommentableMeta
Metadata of the object that a comment is attached to.
Field Type Description id number the ID of the object title string display title type string the type of the object url string url of the object
CurrentUserAttributes
An object listing various related permissions and states for the current user, related to the object it is attached to.
BeatmapsetDiscussionPermissions
TODO: needs a better name.
Name Description can_destroy Can delete the discussion. can_reopen Can reopen the discussion. can_moderate_kudosu Can allow or deny kudosu. can_resolve Can resolve the discussion. vote_score Current vote given to the discussion.
ChatChannelUserAttributes
Name Type Description can_message boolean Can send messages to this channel. can_message_error string? Reason messages cannot be sent to this channel last_read_id number message_id of last message read.
Cursor
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.
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
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-07-06
2022-06-08
2021-10-28
2021-09-01
2021-08-11
2021-06-14
2021-06-09
2021-04-20
2021-02-25
2020-09-08
2020-08-28
2020-05-01
2020-02-18
2019-10-09
2019-07-18
Endpoint
Base URL
The base URL is: https://osu.ppy.sh/api/[version]/
API Versions
This is combined with the base endpoint to determine where requests should be sent.
Version Status v2 current (not yet public, consider unstable and expect breaking changes) v1 legacy api provided by the old site, will be deprecated soon
Authentication
Routes marked with the OAuth label require a valid OAuth2 token for access.
More information about applications you have registered and granted permissions to can be found here.
The API supports the following grant types:
Before you can use the osu!api, you will need to
Registering an OAuth application
Before you can get an OAuth token, you will need to register an OAuth application on your account settings page
To register an OAuth application you will need to provide the:
Name Description Application Name This is the name that will be visible to users of your application. The name of your application cannot be changed. Application Callback URL The URL in your application where users will be sent after authorization.
The Application Callback URL is required when for using Authorization Codes. This may be left blank if you are only using Client Credentials Grants.
Your new OAuth application will have a Client ID and Client Secret ; the Client Secret is like a password for your OAuth application, it should be kept private and do not share it with anyone else.
Authorization Code Grant
The flow to authorize users for your application is:
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:
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:
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.
Make sure to replace <> 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:
Name Description chat.write Allows sending chat messages on a user’s behalf. delegate Allows acting as the owner of a client; only available for Client Credentials Grant. forum.write Allows creating and editing forum posts on a user’s behalf. friends.read Allows reading of the user’s friend list. identify Allows reading of the public profile of the user ( /me ). public Allows reading of publicly available data on behalf of the user.
identify is the default scope for the Authorization Code Grant and always implicitly provided. The Client Credentials Grant does not currently have any default scopes.
Routes marked with lazer are intended for use by the osu!lazer client and not currently available for use with Authorization Code or Client Credentials grants.
Using the chat.write scope requires either
Managing OAuth applications
Your account settings page will show your registered OAuth applications, and all the OAuth applications you have granted permissions to.
Reset Client Secret
You can generate a new Client Secret by choosing to «Reset client secret», however, this will disable all access tokens issued for the application.
Beatmaps
Lookup Beatmap
Response format
Get a User Beatmap score
Return a User’s score on a Beatmap
Response Format
The position returned depends on the requested mode and mods.
Get a User Beatmap scores
Return a User’s scores on a Beatmap
Response Format
Get Beatmap scores
Returns the top scores for a beatmap
Response Format
Get Beatmap scores (temp)
Returns the top scores for a beatmap from newer client.
This is a temporary endpoint.
Response Format
Get Beatmaps
Returns list of beatmaps.
Response format
Field Type Description beatmaps BeatmapCompact[] Includes: beatmapset (with ratings), failtimes, max_combo.
Get Beatmap
Gets beatmap data for the specified beatmap ID.
Response format
Returns Beatmap object. Following attributes are included in the response object when applicable,
Attribute Notes beatmapset Includes ratings property. failtimes max_combo
Get Beatmap Attributes
Returns difficulty attributes of beatmap with specific mode and mods combination.
Response format
Beatmapset Discussions
Get Beatmapset Discussion Posts
Returns the posts of beatmapset discussions.
Response Format
Get Beatmapset Discussion Votes
Returns the votes given to beatmapset discussions.
Response Format
Get Beatmapset Discussions
Returns a list of beatmapset discussions.
Response Format
Changelog
Get Changelog Build
Returns details of the specified build.
Response Format
Get Changelog Listing
Returns a listing of update streams, builds, and changelog entries.
Response Format
Lookup Changelog Build
Returns details of the specified build.
Response Format
Create New PM
This endpoint allows you to create a new PM channel.
Response Format
Field Type new_channel_id channel_id of newly created ChatChannel presence array of ChatChannel message the sent ChatMessage
This endpoint will only allow the creation of PMs initially, group chat support will come later.
Get Updates
This endpoint returns new messages since the given message_id along with updated channel ‘presence’ data.
Response Format
Get Channel Messages
This endpoint returns the chat messages for a specific channel.
Response Format
Returns an array of ChatMessage
Send Message to Channel
This endpoint returns the chat messages for a specific channel.
Response Format
Join Channel
This endpoint allows you to join a public or multiplayer channel.
Response Format
Returns the joined ChatChannel.
Leave Channel
This endpoint allows you to leave a public channel.
Response Format
Mark Channel as Read
Response Format
Get Channel List
This endpoint returns a list of all joinable public channels.
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.
Response Format
Returns ChatChannel with recent_messages attribute. Note that in the case of PM s, 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.
Response Format
Field Type Description channel ChatChannel users UserCompact Users are only visible for PM channels.
Comments
Get Comments
Returns a list comments and their replies up to 2 levels deep.
Response Format
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.
Response Format
Get a Comment
Gets a comment and its replies up to 2 levels deep.
Response Format
Edit Comment
Edit an existing comment.
Response Format
Delete Comment
Deletes the specified comment.
Response Format
Add Comment vote
Upvotes a comment.
Response Format
Remove Comment vote
Un-upvotes a comment.
Response Format
Forum
Reply Topic
Create a post replying to the specified topic.
Response Format
ForumPost with body included.
Create Topic
Create a new topic.
Response Format
Get Topic and Posts
Get topic and its posts.
Response Format
Edit Topic
Edit topic. Only title can be edited through this endpoint.
Response Format
Edit Post
Edit specified forum post.
Response Format
ForumPost with body included.
Search
Searches users and wiki pages.
Response Format
SearchResult
Multiplayer
Get User High Score
Returns detail of highest score of specified user and the surrounding scores.
Response Format
Get Scores
Returns a list of scores for specified playlist item.
Response Format
Get a Score
Returns detail of specified score and the surrounding scores.
Response Format
Get News Listing
Returns a list of news posts and related metadata.
Response Format
Get News Post
Returns details of the specified news post.
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.
Response Format
Returns an object containing Notification and other related attributes.
Field Type has_more boolean whether or not there are more notifications notifications array of Notification unread_count total unread notifications notification_endpoint url to connect to websocket server
Mark Notifications as Read
This endpoint allows you to mark notifications read.
Response Format
OAuth Tokens
Revoke current token
Revokes currently authenticated token.
Ranking
Get Ranking
Gets the current ranking for the specified type and game mode.
Response Format
Get Spotlights
Gets the list of spotlights.
Response Format
Undocumented
/beatmaps//solo/scores
/beatmaps//solo/scores//beatmapsets/events
/beatmapsets//favourites
/chat/presence
/matches
/matches//rooms//rooms//users//rooms//users//rooms//leaderboard
/rooms//playlist//scores
/rooms//playlist//scores//reports
/rooms
/rooms//seasonal-backgrounds
/scores///download
/scores///beatmapsets/search//beatmapsets/lookup
/beatmapsets//friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
Similar to Get User but with authenticated user (token owner) as user id.
Response format
Additionally, statistics_rulesets is included, containing statistics for all rulesets.
Get User Kudosu
Returns kudosu history.
Response format
Get User Scores
This endpoint returns the scores of specified user.
Response format
Array of Score. Following attributes are included in the response object when applicable.
Get User Beatmaps
Returns the beatmaps of specified user.
Type Notes favourite graveyard loved most_played pending Previously unranked ranked Previously ranked_and_approved
Response format
Array of BeatmapPlaycount when type is most_played ; array of Beatmapset, otherwise.
Get User Recent Activity
Returns recent activity.
Response format
Get User
This endpoint returns the detail of specified user.
Response format
Returns User object. The following optional attributes on UserCompact are included:
Get Users
Returns list of users.
Response format
Field Type Description users UserCompact[] Includes: country, cover, groups, statistics_rulesets.
Get Wiki Page
The wiki article or image data.
Response Format
Notification Websocket
Connection
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:
Field Type Description event string See below
logout event
Server will disconnect session after sending this event so don’t try to reconnect.
Field Type Description event string logout
new event
New notification. See Notification object for notification types.
Field Type Description event string new data Notification
read event
Notification has been read.
Field Type Description event string read ids number[] id of Notifications which are read
Object Structures
Beatmap
Represent a beatmap. This extends BeatmapCompact with additional attributes.
Field Type Description accuracy float ar float beatmapset_id integer bpm float? convert boolean count_circles integer count_sliders integer count_spinners integer cs float deleted_at Timestamp? drain float hit_length integer is_scoreable boolean last_updated Timestamp mode_int integer passcount integer playcount integer ranked integer See Rank status for list of possible values. url string
BeatmapCompact
Represent a beatmap.
Field Type Description beatmapset_id integer difficulty_rating float id integer mode GameMode status string See Rank status for list of possible values. total_length integer user_id integer version string
Field Type Description beatmapset Beatmapset|BeatmapsetCompact|null Beatmapset for Beatmap object, BeatmapsetCompact for BeatmapCompact object. null if the beatmap doesn’t have associated beatmapset (e.g. deleted). checksum string? failtimes Failtimes max_combo integer
Failtimes
All fields are optional but there’s always at least one field returned.
Field Type Description exit integer[]? Array of length 100. fail integer[]? Array of length 100.
BeatmapDifficultyAttributes
Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.
Field Type max_combo integer star_rating float
Field Type aim_difficulty float approach_rate float flashlight_difficulty float overall_difficulty float slider_factor float speed_difficulty float
taiko
Field Type stamina_difficulty float rhythm_difficulty float colour_difficulty float approach_rate float great_hit_window float
fruits
mania
Field Type great_hit_window float score_multiplier float
BeatmapPlaycount
Represent the playcount of a beatmap.
Field Type Description beatmap_id number beatmap BeatmapCompact? beatmapset BeatmapsetCompact? count number
BeatmapScores
Field Type Description scores Score[] The list of top scores for the beatmap in descending order. userScore BeatmapUserScore? The score of the current user. This is not returned if the current user does not have a score. Note: will be moved to user_score in the future
BeatmapUserScore
Field Type Description position number The position of the score within the requested beatmap ranking. score Score The details of the score.
Beatmapset
Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.
Field Type Description availability.download_disabled boolean availability.more_information string? bpm float can_be_hyped boolean creator string Username of the mapper at the time of beatmapset creation. discussion_locked boolean hype.current integer hype.required integer is_scoreable boolean last_updated Timestamp legacy_thread_url string? nominations.current integer nominations.required integer ranked integer See Rank status for list of possible values. ranked_date Timestamp? source string storyboard boolean submitted_date Timestamp? tags string
The following attributes are always included as well:
Field has_favourited
BeatmapsetCompact
Represents a beatmapset.
Field Type Description artist string artist_unicode string covers Covers creator string favourite_count number id number nsfw boolean play_count number preview_url string source string status string title string title_unicode string user_id number video boolean
Those fields are optional.
Field Type Description beatmaps Beatmap[] converts current_user_attributes description discussions events genre has_favourited boolean language nominations ratings recent_favourites related_users user
Covers
Field Type cover string cover@2x string card string card@2x string list string list@2x string slimcover string slimcover@2x string
Rank status
The possible values are denoted either as integer or string.
Integer String -2 graveyard -1 wip 0 pending 1 ranked 2 approved 3 qualified 4 loved
BeatmapsetDiscussion
Represents a Beatmapset modding discussion.
Field Type Description beatmap BeatmapCompact? beatmap_id number? beatmapset BeatmapsetCompact? beatmapset_id number can_be_resolved boolean can_grant_kudosu boolean created_at Timestamp current_user_attributes CurrentUserAttributes deleted_at Timestamp? deleted_by_id number? id number kudosu_denied boolean last_post_at Timestamp message_type MessageType parent_id number? posts BeatmapsetDiscussionPost[]? resolved boolean starting_post BeatmapsetDiscussionPost? timestamp number? updated_at Timestamp user_id number
MessageType
Name Description hype mapper_note praise problem review suggestion
BeatmapsetDiscussionPost
Field Type Description beatmapset_discussion_id number created_at Timestamp deleted_at Timestamp? deleted_by_id number? id number last_editor_id number? message string system boolean updated_at Timestamp user_id number
BeatmapsetDiscussionVote
Field Type Description beatmapset_discussion_id number created_at Timestamp id number score number updated_at Timestamp user_id number
Build
Field Type created_at Timestamp display_version string id number update_stream UpdateStream? users number version string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes changelog_entries ChangelogEntry[] If the build has no changelog entries, a placeholder is generated. versions Versions
Versions
ChangelogEntry
Field Type category string created_at Timestamp? github_pull_request_id number? github_url string? id number? major boolean repository string? title string? type string url string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes github_user GithubUser If the changelog entry has no GitHub user, a placeholder is generated. message string? Entry message in Markdown format. Embedded HTML is allowed. message_html string? Entry message in HTML format.
ChatChannel
Represents an individual chat «channel» in the game.
Channel Types
Type Permission Check for Joining/Messaging PUBLIC PRIVATE is player in the allowed groups? (channel.allowed_groups) MULTIPLAYER is player currently in the mp game? SPECTATOR TEMPORARY deprecated PM see below (user_channels) GROUP is player in channel? (user_channels)
For PMs, two factors are taken into account:
ChatMessage
Represents an individual Message within a ChatChannel.
Field Type Description message_id number unique identifier for message sender_id number user_id of the sender channel_id number channel_id of where the message was sent timestamp string when the message was sent, ISO-8601 content string message content is_action boolean was this an action? i.e. /me dances sender UserCompact embedded UserCompact object to save additional api lookups
Comment
Represents an single comment.
Field Type Description commentable_id number ID of the object the comment is attached to commentable_type string type of object the comment is attached to created_at string ISO 8601 date deleted_at string? ISO 8601 date if the comment was deleted; null, otherwise edited_at string? ISO 8601 date if the comment was edited; null, otherwise edited_by_id number? user id of the user that edited the post; null, otherwise id number the ID of the comment legacy_name string? username displayed on legacy comments message string? markdown of the comment’s content message_html string? html version of the comment’s content parent_id number? ID of the comment’s parent pinned boolean Pin status of the comment replies_count number number of replies to the comment updated_at string ISO 8601 date user_id number user ID of the poster votes_count number number of votes
CommentBundle
Comments and related data.
Field Type Description commentable_meta CommentableMeta[] ID of the object the comment is attached to comments Comment[] Array of comments ordered according to sort ; cursor Cursor has_more boolean If there are more comments or replies available has_more_id number? included_comments Comment[] Related comments; e.g. parent comments and nested replies pinned_comments Comment[]? Pinned comments sort string one of the CommentSort types top_level_count number? Number of comments at the top level. Not returned for replies. total number? Total number of comments. Not retuned for replies. user_follow boolean is the current user watching the comment thread? user_votes number[] IDs of the comments in the bundle the current user has upvoted users UserCompact[] array of users related to the comments
CommentSort
Type Sort Fields new created_at (descending), id (descending) old created_at (ascending), id (ascending) top votes_count (descending), created_at (descending), id (descending)
Building cursor for comments listing
The returned response will be for comments after the specified sort fields.
For example, use last loaded comment for the fields value to load more comments. Also make sure to use same sort and parent_id values.
CommentableMeta
Metadata of the object that a comment is attached to.
Field Type Description id number the ID of the object title string display title type string the type of the object url string url of the object
CurrentUserAttributes
An object listing various related permissions and states for the current user, related to the object it is attached to.
BeatmapsetDiscussionPermissions
TODO: needs a better name.
Name Description can_destroy Can delete the discussion. can_reopen Can reopen the discussion. can_moderate_kudosu Can allow or deny kudosu. can_resolve Can resolve the discussion. vote_score Current vote given to the discussion.
ChatChannelUserAttributes
Name Type Description can_message boolean Can send messages to this channel. can_message_error string? Reason messages cannot be sent to this channel last_read_id number message_id of last message read.
Cursor
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.
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
osu!api open beta
Нет аккаунта?
osu!api open beta
I’ve had an API available for a while but until now it has been on a private on-request basis. In order to try and make developing third party services which expand and support osu!, I have added an API key setup and started to document the API.
Documentation will be expanded as I find time to do so! If anyone currently using the API is able to help expand the documentation then please do.
comentarinformal wrote:
Before I spam it with requests that might not exist, is there anything to get user’s information?
(Also, is there anything to login users from this page in other places?)
There is /api/get_user
Gonna write an entry with the information I have about it.
Is there a fair use limit? (e.g. no more than XX requests per day)
For get_user, I suppose there is a mode parameter for getting user information for Taiko, CtB and osu!mania? Or do I have to file an issue in GitHub? Nevermind, I found it, the parameter to add is called «m» 
I have edited the GitHub wiki.
Oh well. I have some questions:
Are only the beatmap and user endpoints available?
The parameter «since» in /get_beatmap how I need to pass the time on it? UTC or unix timestamp?
Do I need to pass the key on the wiki’s API too?
Edit: What the countX values mean? Number of beatmaps?
comentarinformal wrote:
Before I spam it with requests that might not exist, is there anything to get user’s information?
(Also, is there anything to login users from this page in other places?)
I guess I’ll update my userbar too when I find some time.
Damnae wrote:
I guess I’ll update my userbar too when I find some time.
I registered it for osu!userbar, but I also use it for my «Big ugly white signature», they are not on the same webserver, but it works fine
I belive only you and peppy can see the name you used, too.
(Yes I took my lazyness off, it was not that long to update ^^)
@Repflez: I tried using your API-powered signature and I get something weird.
Since I only aim for SS, I have 100% Accuracy all the time, and the Accuracy display is weird.
(I now know that despite having all-SS records, the note hit count for getting 50s and 100s are still counted all the time )
Winshley wrote:
@Repflez: I tried using your API-powered signature and I get something weird.
Since I only aim for SS, I have 100% Accuracy all the time, and the Accuracy display is weird.
(I now know that despite having all-SS records, the note hit count for getting 50s and 100s are still counted all the time )
So that’s what the CountX values mean. Thanks for that. I already went and changed the accuracy to show a centered «100% Accuracy» if it’s 100. Forget that. I ditched the bar on it and used the extra space for showing the PP.
(I love how the 300 count ended overlaping the border)
Repflez wrote:
So that’s what the CountX values mean. Thanks for that.
Yeah. At first I thought that there was something wrong with the API showing 50s and 100s despite having 100% Accuracy, until I actually calculated all 300s + 100s + 50s = «Total Hits» on our profile.
About the 300 overlap though, it does need some fix:
When you reached 10 millions of 300 hits, the last number is cut off. Cookiezi has 17 millions of 300 hits.
I’m not sure how the level bar breaking happens though. I was thinking that it probably because I don’t have any ranked score on osu!mania?
[Archived] getting osu! api token
Нет аккаунта?
[Archived] getting osu! api token
here is the website I am currently using this for https://osu-api-crap.minecreeper0913.repl.co
well since the project I am using is all python and not javascript I am using a new tab browser to just test it and so far the code I am using is
url = («https://osu.ppy.sh/oauth/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=%s» % (code))
the &code=%s is basically just grabbing the code that has been given back by oauth and using that as the url, when I am testing it though I am actually using my code
Never share your client secret, it’s secret for a reason. I would recommend resetting it ASAP.
Are you just typing that URL into your browser or are you actually sending it as a post request with whatever python code you have? Typing the URL into your browser won’t work.
The token endpoint takes the parameters in the body of the request, not as query parameters. You are also missing some parameters, like redirect_uri and grant_type.
If you are using python’s requests library, you can do something like this:
Might have some syntax errors because I wrote that from memory and didn’t check anything in an IDE or by running it.
You can try without specifying the content type in your headers, it might work without it. Very simply, the content type header describes what type of content or data is being sent. As far as I recall, the server is expecting that content type but I could be wrong.
now starting to realize that I might have done this a bit wrong, this is the first time I have used an API for something so everything I am doing is new to me.
So the first thing that is happening is that you press the login to link your osu API to the website, then it grabs your code and redirects you to the home website with the code in the url for example http://www.website.com/code=j9838r9y82g9438gh8243hg384hg, and it is supposed to use that, but when in testing it just returns favicon.ico, and I don’t know what that is or means so I might have to change my get request, another issue is but how would I make it get that auth code?
I don’t know anything about the project you are working on, so unfortunately I don’t think I can really answer any of the questions you’re asking.
I don’t know what you mean by a favicon being returned and I also don’t know what you are using the handle the backend of your site, so I can’t specifically tell you how to grab the code. Whatever you are using should have some way of getting query parameters from the URL.
Oauth2 is a very standardized and should be nearly the same everywhere that uses it. osu! is no exception. I would highly recommend looking up and reading about the authorization code flow that you are trying to use here. There should be a ton of resources and maybe a few code examples as well.
There might not be any videos specific to osu!’s API, but there are definitely Oauth2 tutorial videos and examples out there in probably every programming language, which is what you are dealing with right now.
For example, here is a video I found after a quick Google search that is using Python. I can’t fully comment on its quality since I just skimmed through it, but the general flow that the creator of the video goes over seems like it will at least cover how OAuth2 works in general, even if it’s not in the context of osu!’s API.
And even if you don’t really like reading, there are still some pretty good resources you can use that might help in addition to watching a video. Like this and this for example. Again, I’ve only skimmed through these, but they also seem to be pretty good.
here is the code I use:
NOTE I did not actually use SECRET as the secret I have it as SECRET because its secret
/beatmapsets/events
/beatmapsets//favourites
/chat/presence
/matches
/matches//rooms//rooms//users//rooms//users//rooms//leaderboard
/rooms//playlist//scores
/rooms//playlist//scores//reports
/rooms
/rooms//seasonal-backgrounds
/scores///download
/scores///beatmapsets/search//beatmapsets/lookup
/beatmapsets//friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
Similar to Get User but with authenticated user (token owner) as user id.
Response format
Additionally, statistics_rulesets is included, containing statistics for all rulesets.
Get User Kudosu
Returns kudosu history.
Response format
Get User Scores
This endpoint returns the scores of specified user.
Response format
Array of Score. Following attributes are included in the response object when applicable.
Get User Beatmaps
Returns the beatmaps of specified user.
Type Notes favourite graveyard loved most_played pending Previously unranked ranked Previously ranked_and_approved
Response format
Array of BeatmapPlaycount when type is most_played ; array of Beatmapset, otherwise.
Get User Recent Activity
Returns recent activity.
Response format
Get User
This endpoint returns the detail of specified user.
Response format
Returns User object. The following optional attributes on UserCompact are included:
Get Users
Returns list of users.
Response format
Field Type Description users UserCompact[] Includes: country, cover, groups, statistics_rulesets.
Get Wiki Page
The wiki article or image data.
Response Format
Notification Websocket
Connection
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:
Field Type Description event string See below
logout event
Server will disconnect session after sending this event so don’t try to reconnect.
Field Type Description event string logout
new event
New notification. See Notification object for notification types.
Field Type Description event string new data Notification
read event
Notification has been read.
Field Type Description event string read ids number[] id of Notifications which are read
Object Structures
Beatmap
Represent a beatmap. This extends BeatmapCompact with additional attributes.
Field Type Description accuracy float ar float beatmapset_id integer bpm float? convert boolean count_circles integer count_sliders integer count_spinners integer cs float deleted_at Timestamp? drain float hit_length integer is_scoreable boolean last_updated Timestamp mode_int integer passcount integer playcount integer ranked integer See Rank status for list of possible values. url string
BeatmapCompact
Represent a beatmap.
Field Type Description beatmapset_id integer difficulty_rating float id integer mode GameMode status string See Rank status for list of possible values. total_length integer user_id integer version string
Field Type Description beatmapset Beatmapset|BeatmapsetCompact|null Beatmapset for Beatmap object, BeatmapsetCompact for BeatmapCompact object. null if the beatmap doesn’t have associated beatmapset (e.g. deleted). checksum string? failtimes Failtimes max_combo integer
Failtimes
All fields are optional but there’s always at least one field returned.
Field Type Description exit integer[]? Array of length 100. fail integer[]? Array of length 100.
BeatmapDifficultyAttributes
Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.
Field Type max_combo integer star_rating float
Field Type aim_difficulty float approach_rate float flashlight_difficulty float overall_difficulty float slider_factor float speed_difficulty float
taiko
Field Type stamina_difficulty float rhythm_difficulty float colour_difficulty float approach_rate float great_hit_window float
fruits
mania
Field Type great_hit_window float score_multiplier float
BeatmapPlaycount
Represent the playcount of a beatmap.
Field Type Description beatmap_id number beatmap BeatmapCompact? beatmapset BeatmapsetCompact? count number
BeatmapScores
Field Type Description scores Score[] The list of top scores for the beatmap in descending order. userScore BeatmapUserScore? The score of the current user. This is not returned if the current user does not have a score. Note: will be moved to user_score in the future
BeatmapUserScore
Field Type Description position number The position of the score within the requested beatmap ranking. score Score The details of the score.
Beatmapset
Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.
Field Type Description availability.download_disabled boolean availability.more_information string? bpm float can_be_hyped boolean creator string Username of the mapper at the time of beatmapset creation. discussion_locked boolean hype.current integer hype.required integer is_scoreable boolean last_updated Timestamp legacy_thread_url string? nominations.current integer nominations.required integer ranked integer See Rank status for list of possible values. ranked_date Timestamp? source string storyboard boolean submitted_date Timestamp? tags string
The following attributes are always included as well:
Field has_favourited
BeatmapsetCompact
Represents a beatmapset.
Field Type Description artist string artist_unicode string covers Covers creator string favourite_count number id number nsfw boolean play_count number preview_url string source string status string title string title_unicode string user_id number video boolean
Those fields are optional.
Field Type Description beatmaps Beatmap[] converts current_user_attributes description discussions events genre has_favourited boolean language nominations ratings recent_favourites related_users user
Covers
Field Type cover string cover@2x string card string card@2x string list string list@2x string slimcover string slimcover@2x string
Rank status
The possible values are denoted either as integer or string.
Integer String -2 graveyard -1 wip 0 pending 1 ranked 2 approved 3 qualified 4 loved
BeatmapsetDiscussion
Represents a Beatmapset modding discussion.
Field Type Description beatmap BeatmapCompact? beatmap_id number? beatmapset BeatmapsetCompact? beatmapset_id number can_be_resolved boolean can_grant_kudosu boolean created_at Timestamp current_user_attributes CurrentUserAttributes deleted_at Timestamp? deleted_by_id number? id number kudosu_denied boolean last_post_at Timestamp message_type MessageType parent_id number? posts BeatmapsetDiscussionPost[]? resolved boolean starting_post BeatmapsetDiscussionPost? timestamp number? updated_at Timestamp user_id number
MessageType
Name Description hype mapper_note praise problem review suggestion
BeatmapsetDiscussionPost
Field Type Description beatmapset_discussion_id number created_at Timestamp deleted_at Timestamp? deleted_by_id number? id number last_editor_id number? message string system boolean updated_at Timestamp user_id number
BeatmapsetDiscussionVote
Field Type Description beatmapset_discussion_id number created_at Timestamp id number score number updated_at Timestamp user_id number
Build
Field Type created_at Timestamp display_version string id number update_stream UpdateStream? users number version string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes changelog_entries ChangelogEntry[] If the build has no changelog entries, a placeholder is generated. versions Versions
Versions
ChangelogEntry
Field Type category string created_at Timestamp? github_pull_request_id number? github_url string? id number? major boolean repository string? title string? type string url string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes github_user GithubUser If the changelog entry has no GitHub user, a placeholder is generated. message string? Entry message in Markdown format. Embedded HTML is allowed. message_html string? Entry message in HTML format.
ChatChannel
Represents an individual chat «channel» in the game.
Channel Types
Type Permission Check for Joining/Messaging PUBLIC PRIVATE is player in the allowed groups? (channel.allowed_groups) MULTIPLAYER is player currently in the mp game? SPECTATOR TEMPORARY deprecated PM see below (user_channels) GROUP is player in channel? (user_channels)
For PMs, two factors are taken into account:
ChatMessage
Represents an individual Message within a ChatChannel.
Field Type Description message_id number unique identifier for message sender_id number user_id of the sender channel_id number channel_id of where the message was sent timestamp string when the message was sent, ISO-8601 content string message content is_action boolean was this an action? i.e. /me dances sender UserCompact embedded UserCompact object to save additional api lookups
Comment
Represents an single comment.
Field Type Description commentable_id number ID of the object the comment is attached to commentable_type string type of object the comment is attached to created_at string ISO 8601 date deleted_at string? ISO 8601 date if the comment was deleted; null, otherwise edited_at string? ISO 8601 date if the comment was edited; null, otherwise edited_by_id number? user id of the user that edited the post; null, otherwise id number the ID of the comment legacy_name string? username displayed on legacy comments message string? markdown of the comment’s content message_html string? html version of the comment’s content parent_id number? ID of the comment’s parent pinned boolean Pin status of the comment replies_count number number of replies to the comment updated_at string ISO 8601 date user_id number user ID of the poster votes_count number number of votes
CommentBundle
Comments and related data.
Field Type Description commentable_meta CommentableMeta[] ID of the object the comment is attached to comments Comment[] Array of comments ordered according to sort ; cursor Cursor has_more boolean If there are more comments or replies available has_more_id number? included_comments Comment[] Related comments; e.g. parent comments and nested replies pinned_comments Comment[]? Pinned comments sort string one of the CommentSort types top_level_count number? Number of comments at the top level. Not returned for replies. total number? Total number of comments. Not retuned for replies. user_follow boolean is the current user watching the comment thread? user_votes number[] IDs of the comments in the bundle the current user has upvoted users UserCompact[] array of users related to the comments
CommentSort
Type Sort Fields new created_at (descending), id (descending) old created_at (ascending), id (ascending) top votes_count (descending), created_at (descending), id (descending)
Building cursor for comments listing
The returned response will be for comments after the specified sort fields.
For example, use last loaded comment for the fields value to load more comments. Also make sure to use same sort and parent_id values.
CommentableMeta
Metadata of the object that a comment is attached to.
Field Type Description id number the ID of the object title string display title type string the type of the object url string url of the object
CurrentUserAttributes
An object listing various related permissions and states for the current user, related to the object it is attached to.
BeatmapsetDiscussionPermissions
TODO: needs a better name.
Name Description can_destroy Can delete the discussion. can_reopen Can reopen the discussion. can_moderate_kudosu Can allow or deny kudosu. can_resolve Can resolve the discussion. vote_score Current vote given to the discussion.
ChatChannelUserAttributes
Name Type Description can_message boolean Can send messages to this channel. can_message_error string? Reason messages cannot be sent to this channel last_read_id number message_id of last message read.
Cursor
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.
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
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-07-06
2022-06-08
2021-10-28
2021-09-01
2021-08-11
2021-06-14
2021-06-09
2021-04-20
2021-02-25
2020-09-08
2020-08-28
2020-05-01
2020-02-18
2019-10-09
2019-07-18
Endpoint
Base URL
The base URL is: https://osu.ppy.sh/api/[version]/
API Versions
This is combined with the base endpoint to determine where requests should be sent.
Version Status v2 current (not yet public, consider unstable and expect breaking changes) v1 legacy api provided by the old site, will be deprecated soon
Authentication
Routes marked with the OAuth label require a valid OAuth2 token for access.
More information about applications you have registered and granted permissions to can be found here.
The API supports the following grant types:
Before you can use the osu!api, you will need to
Registering an OAuth application
Before you can get an OAuth token, you will need to register an OAuth application on your account settings page
To register an OAuth application you will need to provide the:
Name Description Application Name This is the name that will be visible to users of your application. The name of your application cannot be changed. Application Callback URL The URL in your application where users will be sent after authorization.
The Application Callback URL is required when for using Authorization Codes. This may be left blank if you are only using Client Credentials Grants.
Your new OAuth application will have a Client ID and Client Secret ; the Client Secret is like a password for your OAuth application, it should be kept private and do not share it with anyone else.
Authorization Code Grant
The flow to authorize users for your application is:
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:
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:
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.
Make sure to replace <> 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:
Name Description chat.write Allows sending chat messages on a user’s behalf. delegate Allows acting as the owner of a client; only available for Client Credentials Grant. forum.write Allows creating and editing forum posts on a user’s behalf. friends.read Allows reading of the user’s friend list. identify Allows reading of the public profile of the user ( /me ). public Allows reading of publicly available data on behalf of the user.
identify is the default scope for the Authorization Code Grant and always implicitly provided. The Client Credentials Grant does not currently have any default scopes.
Routes marked with lazer are intended for use by the osu!lazer client and not currently available for use with Authorization Code or Client Credentials grants.
Using the chat.write scope requires either
Managing OAuth applications
Your account settings page will show your registered OAuth applications, and all the OAuth applications you have granted permissions to.
Reset Client Secret
You can generate a new Client Secret by choosing to «Reset client secret», however, this will disable all access tokens issued for the application.
Beatmaps
Lookup Beatmap
Response format
Get a User Beatmap score
Return a User’s score on a Beatmap
Response Format
The position returned depends on the requested mode and mods.
Get a User Beatmap scores
Return a User’s scores on a Beatmap
Response Format
Get Beatmap scores
Returns the top scores for a beatmap
Response Format
Get Beatmap scores (temp)
Returns the top scores for a beatmap from newer client.
This is a temporary endpoint.
Response Format
Get Beatmaps
Returns list of beatmaps.
Response format
Field Type Description beatmaps BeatmapCompact[] Includes: beatmapset (with ratings), failtimes, max_combo.
Get Beatmap
Gets beatmap data for the specified beatmap ID.
Response format
Returns Beatmap object. Following attributes are included in the response object when applicable,
Attribute Notes beatmapset Includes ratings property. failtimes max_combo
Get Beatmap Attributes
Returns difficulty attributes of beatmap with specific mode and mods combination.
Response format
Beatmapset Discussions
Get Beatmapset Discussion Posts
Returns the posts of beatmapset discussions.
Response Format
Get Beatmapset Discussion Votes
Returns the votes given to beatmapset discussions.
Response Format
Get Beatmapset Discussions
Returns a list of beatmapset discussions.
Response Format
Changelog
Get Changelog Build
Returns details of the specified build.
Response Format
Get Changelog Listing
Returns a listing of update streams, builds, and changelog entries.
Response Format
Lookup Changelog Build
Returns details of the specified build.
Response Format
Create New PM
This endpoint allows you to create a new PM channel.
Response Format
Field Type new_channel_id channel_id of newly created ChatChannel presence array of ChatChannel message the sent ChatMessage
This endpoint will only allow the creation of PMs initially, group chat support will come later.
Get Updates
This endpoint returns new messages since the given message_id along with updated channel ‘presence’ data.
Response Format
Get Channel Messages
This endpoint returns the chat messages for a specific channel.
Response Format
Returns an array of ChatMessage
Send Message to Channel
This endpoint returns the chat messages for a specific channel.
Response Format
Join Channel
This endpoint allows you to join a public or multiplayer channel.
Response Format
Returns the joined ChatChannel.
Leave Channel
This endpoint allows you to leave a public channel.
Response Format
Mark Channel as Read
Response Format
Get Channel List
This endpoint returns a list of all joinable public channels.
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.
Response Format
Returns ChatChannel with recent_messages attribute. Note that in the case of PM s, 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.
Response Format
Field Type Description channel ChatChannel users UserCompact Users are only visible for PM channels.
Comments
Get Comments
Returns a list comments and their replies up to 2 levels deep.
Response Format
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.
Response Format
Get a Comment
Gets a comment and its replies up to 2 levels deep.
Response Format
Edit Comment
Edit an existing comment.
Response Format
Delete Comment
Deletes the specified comment.
Response Format
Add Comment vote
Upvotes a comment.
Response Format
Remove Comment vote
Un-upvotes a comment.
Response Format
Forum
Reply Topic
Create a post replying to the specified topic.
Response Format
ForumPost with body included.
Create Topic
Create a new topic.
Response Format
Get Topic and Posts
Get topic and its posts.
Response Format
Edit Topic
Edit topic. Only title can be edited through this endpoint.
Response Format
Edit Post
Edit specified forum post.
Response Format
ForumPost with body included.
Search
Searches users and wiki pages.
Response Format
SearchResult
Multiplayer
Get User High Score
Returns detail of highest score of specified user and the surrounding scores.
Response Format
Get Scores
Returns a list of scores for specified playlist item.
Response Format
Get a Score
Returns detail of specified score and the surrounding scores.
Response Format
Get News Listing
Returns a list of news posts and related metadata.
Response Format
Get News Post
Returns details of the specified news post.
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.
Response Format
Returns an object containing Notification and other related attributes.
Field Type has_more boolean whether or not there are more notifications notifications array of Notification unread_count total unread notifications notification_endpoint url to connect to websocket server
Mark Notifications as Read
This endpoint allows you to mark notifications read.
Response Format
OAuth Tokens
Revoke current token
Revokes currently authenticated token.
Ranking
Get Ranking
Gets the current ranking for the specified type and game mode.
Response Format
Get Spotlights
Gets the list of spotlights.
Response Format
Undocumented
/beatmaps//solo/scores
/beatmaps//solo/scores//beatmapsets/events
/beatmapsets//favourites
/chat/presence
/matches
/matches//rooms//rooms//users//rooms//users//rooms//leaderboard
/rooms//playlist//scores
/rooms//playlist//scores//reports
/rooms
/rooms//seasonal-backgrounds
/scores///download
/scores///beatmapsets/search//beatmapsets/lookup
/beatmapsets//friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
Similar to Get User but with authenticated user (token owner) as user id.
Response format
Additionally, statistics_rulesets is included, containing statistics for all rulesets.
Get User Kudosu
Returns kudosu history.
Response format
Get User Scores
This endpoint returns the scores of specified user.
Response format
Array of Score. Following attributes are included in the response object when applicable.
Get User Beatmaps
Returns the beatmaps of specified user.
Type Notes favourite graveyard loved most_played pending Previously unranked ranked Previously ranked_and_approved
Response format
Array of BeatmapPlaycount when type is most_played ; array of Beatmapset, otherwise.
Get User Recent Activity
Returns recent activity.
Response format
Get User
This endpoint returns the detail of specified user.
Response format
Returns User object. The following optional attributes on UserCompact are included:
Get Users
Returns list of users.
Response format
Field Type Description users UserCompact[] Includes: country, cover, groups, statistics_rulesets.
Get Wiki Page
The wiki article or image data.
Response Format
Notification Websocket
Connection
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:
Field Type Description event string See below
logout event
Server will disconnect session after sending this event so don’t try to reconnect.
Field Type Description event string logout
new event
New notification. See Notification object for notification types.
Field Type Description event string new data Notification
read event
Notification has been read.
Field Type Description event string read ids number[] id of Notifications which are read
Object Structures
Beatmap
Represent a beatmap. This extends BeatmapCompact with additional attributes.
Field Type Description accuracy float ar float beatmapset_id integer bpm float? convert boolean count_circles integer count_sliders integer count_spinners integer cs float deleted_at Timestamp? drain float hit_length integer is_scoreable boolean last_updated Timestamp mode_int integer passcount integer playcount integer ranked integer See Rank status for list of possible values. url string
BeatmapCompact
Represent a beatmap.
Field Type Description beatmapset_id integer difficulty_rating float id integer mode GameMode status string See Rank status for list of possible values. total_length integer user_id integer version string
Field Type Description beatmapset Beatmapset|BeatmapsetCompact|null Beatmapset for Beatmap object, BeatmapsetCompact for BeatmapCompact object. null if the beatmap doesn’t have associated beatmapset (e.g. deleted). checksum string? failtimes Failtimes max_combo integer
Failtimes
All fields are optional but there’s always at least one field returned.
Field Type Description exit integer[]? Array of length 100. fail integer[]? Array of length 100.
BeatmapDifficultyAttributes
Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.
Field Type max_combo integer star_rating float
Field Type aim_difficulty float approach_rate float flashlight_difficulty float overall_difficulty float slider_factor float speed_difficulty float
taiko
Field Type stamina_difficulty float rhythm_difficulty float colour_difficulty float approach_rate float great_hit_window float
fruits
mania
Field Type great_hit_window float score_multiplier float
BeatmapPlaycount
Represent the playcount of a beatmap.
Field Type Description beatmap_id number beatmap BeatmapCompact? beatmapset BeatmapsetCompact? count number
BeatmapScores
Field Type Description scores Score[] The list of top scores for the beatmap in descending order. userScore BeatmapUserScore? The score of the current user. This is not returned if the current user does not have a score. Note: will be moved to user_score in the future
BeatmapUserScore
Field Type Description position number The position of the score within the requested beatmap ranking. score Score The details of the score.
Beatmapset
Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.
Field Type Description availability.download_disabled boolean availability.more_information string? bpm float can_be_hyped boolean creator string Username of the mapper at the time of beatmapset creation. discussion_locked boolean hype.current integer hype.required integer is_scoreable boolean last_updated Timestamp legacy_thread_url string? nominations.current integer nominations.required integer ranked integer See Rank status for list of possible values. ranked_date Timestamp? source string storyboard boolean submitted_date Timestamp? tags string
The following attributes are always included as well:
Field has_favourited
BeatmapsetCompact
Represents a beatmapset.
Field Type Description artist string artist_unicode string covers Covers creator string favourite_count number id number nsfw boolean play_count number preview_url string source string status string title string title_unicode string user_id number video boolean
Those fields are optional.
Field Type Description beatmaps Beatmap[] converts current_user_attributes description discussions events genre has_favourited boolean language nominations ratings recent_favourites related_users user
Covers
Field Type cover string cover@2x string card string card@2x string list string list@2x string slimcover string slimcover@2x string
Rank status
The possible values are denoted either as integer or string.
Integer String -2 graveyard -1 wip 0 pending 1 ranked 2 approved 3 qualified 4 loved
BeatmapsetDiscussion
Represents a Beatmapset modding discussion.
Field Type Description beatmap BeatmapCompact? beatmap_id number? beatmapset BeatmapsetCompact? beatmapset_id number can_be_resolved boolean can_grant_kudosu boolean created_at Timestamp current_user_attributes CurrentUserAttributes deleted_at Timestamp? deleted_by_id number? id number kudosu_denied boolean last_post_at Timestamp message_type MessageType parent_id number? posts BeatmapsetDiscussionPost[]? resolved boolean starting_post BeatmapsetDiscussionPost? timestamp number? updated_at Timestamp user_id number
MessageType
Name Description hype mapper_note praise problem review suggestion
BeatmapsetDiscussionPost
Field Type Description beatmapset_discussion_id number created_at Timestamp deleted_at Timestamp? deleted_by_id number? id number last_editor_id number? message string system boolean updated_at Timestamp user_id number
BeatmapsetDiscussionVote
Field Type Description beatmapset_discussion_id number created_at Timestamp id number score number updated_at Timestamp user_id number
Build
Field Type created_at Timestamp display_version string id number update_stream UpdateStream? users number version string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes changelog_entries ChangelogEntry[] If the build has no changelog entries, a placeholder is generated. versions Versions
Versions
ChangelogEntry
Field Type category string created_at Timestamp? github_pull_request_id number? github_url string? id number? major boolean repository string? title string? type string url string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes github_user GithubUser If the changelog entry has no GitHub user, a placeholder is generated. message string? Entry message in Markdown format. Embedded HTML is allowed. message_html string? Entry message in HTML format.
ChatChannel
Represents an individual chat «channel» in the game.
Channel Types
Type Permission Check for Joining/Messaging PUBLIC PRIVATE is player in the allowed groups? (channel.allowed_groups) MULTIPLAYER is player currently in the mp game? SPECTATOR TEMPORARY deprecated PM see below (user_channels) GROUP is player in channel? (user_channels)
For PMs, two factors are taken into account:
ChatMessage
Represents an individual Message within a ChatChannel.
Field Type Description message_id number unique identifier for message sender_id number user_id of the sender channel_id number channel_id of where the message was sent timestamp string when the message was sent, ISO-8601 content string message content is_action boolean was this an action? i.e. /me dances sender UserCompact embedded UserCompact object to save additional api lookups
Comment
Represents an single comment.
Field Type Description commentable_id number ID of the object the comment is attached to commentable_type string type of object the comment is attached to created_at string ISO 8601 date deleted_at string? ISO 8601 date if the comment was deleted; null, otherwise edited_at string? ISO 8601 date if the comment was edited; null, otherwise edited_by_id number? user id of the user that edited the post; null, otherwise id number the ID of the comment legacy_name string? username displayed on legacy comments message string? markdown of the comment’s content message_html string? html version of the comment’s content parent_id number? ID of the comment’s parent pinned boolean Pin status of the comment replies_count number number of replies to the comment updated_at string ISO 8601 date user_id number user ID of the poster votes_count number number of votes
CommentBundle
Comments and related data.
Field Type Description commentable_meta CommentableMeta[] ID of the object the comment is attached to comments Comment[] Array of comments ordered according to sort ; cursor Cursor has_more boolean If there are more comments or replies available has_more_id number? included_comments Comment[] Related comments; e.g. parent comments and nested replies pinned_comments Comment[]? Pinned comments sort string one of the CommentSort types top_level_count number? Number of comments at the top level. Not returned for replies. total number? Total number of comments. Not retuned for replies. user_follow boolean is the current user watching the comment thread? user_votes number[] IDs of the comments in the bundle the current user has upvoted users UserCompact[] array of users related to the comments
CommentSort
Type Sort Fields new created_at (descending), id (descending) old created_at (ascending), id (ascending) top votes_count (descending), created_at (descending), id (descending)
Building cursor for comments listing
The returned response will be for comments after the specified sort fields.
For example, use last loaded comment for the fields value to load more comments. Also make sure to use same sort and parent_id values.
CommentableMeta
Metadata of the object that a comment is attached to.
Field Type Description id number the ID of the object title string display title type string the type of the object url string url of the object
CurrentUserAttributes
An object listing various related permissions and states for the current user, related to the object it is attached to.
BeatmapsetDiscussionPermissions
TODO: needs a better name.
Name Description can_destroy Can delete the discussion. can_reopen Can reopen the discussion. can_moderate_kudosu Can allow or deny kudosu. can_resolve Can resolve the discussion. vote_score Current vote given to the discussion.
ChatChannelUserAttributes
Name Type Description can_message boolean Can send messages to this channel. can_message_error string? Reason messages cannot be sent to this channel last_read_id number message_id of last message read.
Cursor
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.
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
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-07-06
2022-06-08
2021-10-28
2021-09-01
2021-08-11
2021-06-14
2021-06-09
2021-04-20
2021-02-25
2020-09-08
2020-08-28
2020-05-01
2020-02-18
2019-10-09
2019-07-18
Endpoint
Base URL
The base URL is: https://osu.ppy.sh/api/[version]/
API Versions
This is combined with the base endpoint to determine where requests should be sent.
Version Status v2 current (not yet public, consider unstable and expect breaking changes) v1 legacy api provided by the old site, will be deprecated soon
Authentication
Routes marked with the OAuth label require a valid OAuth2 token for access.
More information about applications you have registered and granted permissions to can be found here.
The API supports the following grant types:
Before you can use the osu!api, you will need to
Registering an OAuth application
Before you can get an OAuth token, you will need to register an OAuth application on your account settings page
To register an OAuth application you will need to provide the:
Name Description Application Name This is the name that will be visible to users of your application. The name of your application cannot be changed. Application Callback URL The URL in your application where users will be sent after authorization.
The Application Callback URL is required when for using Authorization Codes. This may be left blank if you are only using Client Credentials Grants.
Your new OAuth application will have a Client ID and Client Secret ; the Client Secret is like a password for your OAuth application, it should be kept private and do not share it with anyone else.
Authorization Code Grant
The flow to authorize users for your application is:
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:
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:
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.
Make sure to replace <> 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:
Name Description chat.write Allows sending chat messages on a user’s behalf. delegate Allows acting as the owner of a client; only available for Client Credentials Grant. forum.write Allows creating and editing forum posts on a user’s behalf. friends.read Allows reading of the user’s friend list. identify Allows reading of the public profile of the user ( /me ). public Allows reading of publicly available data on behalf of the user.
identify is the default scope for the Authorization Code Grant and always implicitly provided. The Client Credentials Grant does not currently have any default scopes.
Routes marked with lazer are intended for use by the osu!lazer client and not currently available for use with Authorization Code or Client Credentials grants.
Using the chat.write scope requires either
Managing OAuth applications
Your account settings page will show your registered OAuth applications, and all the OAuth applications you have granted permissions to.
Reset Client Secret
You can generate a new Client Secret by choosing to «Reset client secret», however, this will disable all access tokens issued for the application.
Beatmaps
Lookup Beatmap
Response format
Get a User Beatmap score
Return a User’s score on a Beatmap
Response Format
The position returned depends on the requested mode and mods.
Get a User Beatmap scores
Return a User’s scores on a Beatmap
Response Format
Get Beatmap scores
Returns the top scores for a beatmap
Response Format
Get Beatmap scores (temp)
Returns the top scores for a beatmap from newer client.
This is a temporary endpoint.
Response Format
Get Beatmaps
Returns list of beatmaps.
Response format
Field Type Description beatmaps BeatmapCompact[] Includes: beatmapset (with ratings), failtimes, max_combo.
Get Beatmap
Gets beatmap data for the specified beatmap ID.
Response format
Returns Beatmap object. Following attributes are included in the response object when applicable,
Attribute Notes beatmapset Includes ratings property. failtimes max_combo
Get Beatmap Attributes
Returns difficulty attributes of beatmap with specific mode and mods combination.
Response format
Beatmapset Discussions
Get Beatmapset Discussion Posts
Returns the posts of beatmapset discussions.
Response Format
Get Beatmapset Discussion Votes
Returns the votes given to beatmapset discussions.
Response Format
Get Beatmapset Discussions
Returns a list of beatmapset discussions.
Response Format
Changelog
Get Changelog Build
Returns details of the specified build.
Response Format
Get Changelog Listing
Returns a listing of update streams, builds, and changelog entries.
Response Format
Lookup Changelog Build
Returns details of the specified build.
Response Format
Create New PM
This endpoint allows you to create a new PM channel.
Response Format
Field Type new_channel_id channel_id of newly created ChatChannel presence array of ChatChannel message the sent ChatMessage
This endpoint will only allow the creation of PMs initially, group chat support will come later.
Get Updates
This endpoint returns new messages since the given message_id along with updated channel ‘presence’ data.
Response Format
Get Channel Messages
This endpoint returns the chat messages for a specific channel.
Response Format
Returns an array of ChatMessage
Send Message to Channel
This endpoint returns the chat messages for a specific channel.
Response Format
Join Channel
This endpoint allows you to join a public or multiplayer channel.
Response Format
Returns the joined ChatChannel.
Leave Channel
This endpoint allows you to leave a public channel.
Response Format
Mark Channel as Read
Response Format
Get Channel List
This endpoint returns a list of all joinable public channels.
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.
Response Format
Returns ChatChannel with recent_messages attribute. Note that in the case of PM s, 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.
Response Format
Field Type Description channel ChatChannel users UserCompact Users are only visible for PM channels.
Comments
Get Comments
Returns a list comments and their replies up to 2 levels deep.
Response Format
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.
Response Format
Get a Comment
Gets a comment and its replies up to 2 levels deep.
Response Format
Edit Comment
Edit an existing comment.
Response Format
Delete Comment
Deletes the specified comment.
Response Format
Add Comment vote
Upvotes a comment.
Response Format
Remove Comment vote
Un-upvotes a comment.
Response Format
Forum
Reply Topic
Create a post replying to the specified topic.
Response Format
ForumPost with body included.
Create Topic
Create a new topic.
Response Format
Get Topic and Posts
Get topic and its posts.
Response Format
Edit Topic
Edit topic. Only title can be edited through this endpoint.
Response Format
Edit Post
Edit specified forum post.
Response Format
ForumPost with body included.
Search
Searches users and wiki pages.
Response Format
SearchResult
Multiplayer
Get User High Score
Returns detail of highest score of specified user and the surrounding scores.
Response Format
Get Scores
Returns a list of scores for specified playlist item.
Response Format
Get a Score
Returns detail of specified score and the surrounding scores.
Response Format
Get News Listing
Returns a list of news posts and related metadata.
Response Format
Get News Post
Returns details of the specified news post.
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.
Response Format
Returns an object containing Notification and other related attributes.
Field Type has_more boolean whether or not there are more notifications notifications array of Notification unread_count total unread notifications notification_endpoint url to connect to websocket server
Mark Notifications as Read
This endpoint allows you to mark notifications read.
Response Format
OAuth Tokens
Revoke current token
Revokes currently authenticated token.
Ranking
Get Ranking
Gets the current ranking for the specified type and game mode.
Response Format
Get Spotlights
Gets the list of spotlights.
Response Format
Undocumented
/beatmaps//solo/scores
/beatmaps//solo/scores//beatmapsets/events
/beatmapsets//favourites
/chat/presence
/matches
/matches//rooms//rooms//users//rooms//users//rooms//leaderboard
/rooms//playlist//scores
/rooms//playlist//scores//reports
/rooms
/rooms//seasonal-backgrounds
/scores///download
/scores///beatmapsets/search//beatmapsets/lookup
/beatmapsets//friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
Similar to Get User but with authenticated user (token owner) as user id.
Response format
Additionally, statistics_rulesets is included, containing statistics for all rulesets.
Get User Kudosu
Returns kudosu history.
Response format
Get User Scores
This endpoint returns the scores of specified user.
Response format
Array of Score. Following attributes are included in the response object when applicable.
Get User Beatmaps
Returns the beatmaps of specified user.
Type Notes favourite graveyard loved most_played pending Previously unranked ranked Previously ranked_and_approved
Response format
Array of BeatmapPlaycount when type is most_played ; array of Beatmapset, otherwise.
Get User Recent Activity
Returns recent activity.
Response format
Get User
This endpoint returns the detail of specified user.
Response format
Returns User object. The following optional attributes on UserCompact are included:
Get Users
Returns list of users.
Response format
Field Type Description users UserCompact[] Includes: country, cover, groups, statistics_rulesets.
Get Wiki Page
The wiki article or image data.
Response Format
Notification Websocket
Connection
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:
Field Type Description event string See below
logout event
Server will disconnect session after sending this event so don’t try to reconnect.
Field Type Description event string logout
new event
New notification. See Notification object for notification types.
Field Type Description event string new data Notification
read event
Notification has been read.
Field Type Description event string read ids number[] id of Notifications which are read
Object Structures
Beatmap
Represent a beatmap. This extends BeatmapCompact with additional attributes.
Field Type Description accuracy float ar float beatmapset_id integer bpm float? convert boolean count_circles integer count_sliders integer count_spinners integer cs float deleted_at Timestamp? drain float hit_length integer is_scoreable boolean last_updated Timestamp mode_int integer passcount integer playcount integer ranked integer See Rank status for list of possible values. url string
BeatmapCompact
Represent a beatmap.
Field Type Description beatmapset_id integer difficulty_rating float id integer mode GameMode status string See Rank status for list of possible values. total_length integer user_id integer version string
Field Type Description beatmapset Beatmapset|BeatmapsetCompact|null Beatmapset for Beatmap object, BeatmapsetCompact for BeatmapCompact object. null if the beatmap doesn’t have associated beatmapset (e.g. deleted). checksum string? failtimes Failtimes max_combo integer
Failtimes
All fields are optional but there’s always at least one field returned.
Field Type Description exit integer[]? Array of length 100. fail integer[]? Array of length 100.
BeatmapDifficultyAttributes
Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.
Field Type max_combo integer star_rating float
Field Type aim_difficulty float approach_rate float flashlight_difficulty float overall_difficulty float slider_factor float speed_difficulty float
taiko
Field Type stamina_difficulty float rhythm_difficulty float colour_difficulty float approach_rate float great_hit_window float
fruits
mania
Field Type great_hit_window float score_multiplier float
BeatmapPlaycount
Represent the playcount of a beatmap.
Field Type Description beatmap_id number beatmap BeatmapCompact? beatmapset BeatmapsetCompact? count number
BeatmapScores
Field Type Description scores Score[] The list of top scores for the beatmap in descending order. userScore BeatmapUserScore? The score of the current user. This is not returned if the current user does not have a score. Note: will be moved to user_score in the future
BeatmapUserScore
Field Type Description position number The position of the score within the requested beatmap ranking. score Score The details of the score.
Beatmapset
Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.
Field Type Description availability.download_disabled boolean availability.more_information string? bpm float can_be_hyped boolean creator string Username of the mapper at the time of beatmapset creation. discussion_locked boolean hype.current integer hype.required integer is_scoreable boolean last_updated Timestamp legacy_thread_url string? nominations.current integer nominations.required integer ranked integer See Rank status for list of possible values. ranked_date Timestamp? source string storyboard boolean submitted_date Timestamp? tags string
The following attributes are always included as well:
Field has_favourited
BeatmapsetCompact
Represents a beatmapset.
Field Type Description artist string artist_unicode string covers Covers creator string favourite_count number id number nsfw boolean play_count number preview_url string source string status string title string title_unicode string user_id number video boolean
Those fields are optional.
Field Type Description beatmaps Beatmap[] converts current_user_attributes description discussions events genre has_favourited boolean language nominations ratings recent_favourites related_users user
Covers
Field Type cover string cover@2x string card string card@2x string list string list@2x string slimcover string slimcover@2x string
Rank status
The possible values are denoted either as integer or string.
Integer String -2 graveyard -1 wip 0 pending 1 ranked 2 approved 3 qualified 4 loved
BeatmapsetDiscussion
Represents a Beatmapset modding discussion.
Field Type Description beatmap BeatmapCompact? beatmap_id number? beatmapset BeatmapsetCompact? beatmapset_id number can_be_resolved boolean can_grant_kudosu boolean created_at Timestamp current_user_attributes CurrentUserAttributes deleted_at Timestamp? deleted_by_id number? id number kudosu_denied boolean last_post_at Timestamp message_type MessageType parent_id number? posts BeatmapsetDiscussionPost[]? resolved boolean starting_post BeatmapsetDiscussionPost? timestamp number? updated_at Timestamp user_id number
MessageType
Name Description hype mapper_note praise problem review suggestion
BeatmapsetDiscussionPost
Field Type Description beatmapset_discussion_id number created_at Timestamp deleted_at Timestamp? deleted_by_id number? id number last_editor_id number? message string system boolean updated_at Timestamp user_id number
BeatmapsetDiscussionVote
Field Type Description beatmapset_discussion_id number created_at Timestamp id number score number updated_at Timestamp user_id number
Build
Field Type created_at Timestamp display_version string id number update_stream UpdateStream? users number version string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes changelog_entries ChangelogEntry[] If the build has no changelog entries, a placeholder is generated. versions Versions
Versions
ChangelogEntry
Field Type category string created_at Timestamp? github_pull_request_id number? github_url string? id number? major boolean repository string? title string? type string url string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes github_user GithubUser If the changelog entry has no GitHub user, a placeholder is generated. message string? Entry message in Markdown format. Embedded HTML is allowed. message_html string? Entry message in HTML format.
ChatChannel
Represents an individual chat «channel» in the game.
Channel Types
Type Permission Check for Joining/Messaging PUBLIC PRIVATE is player in the allowed groups? (channel.allowed_groups) MULTIPLAYER is player currently in the mp game? SPECTATOR TEMPORARY deprecated PM see below (user_channels) GROUP is player in channel? (user_channels)
For PMs, two factors are taken into account:
ChatMessage
Represents an individual Message within a ChatChannel.
Field Type Description message_id number unique identifier for message sender_id number user_id of the sender channel_id number channel_id of where the message was sent timestamp string when the message was sent, ISO-8601 content string message content is_action boolean was this an action? i.e. /me dances sender UserCompact embedded UserCompact object to save additional api lookups
Comment
Represents an single comment.
Field Type Description commentable_id number ID of the object the comment is attached to commentable_type string type of object the comment is attached to created_at string ISO 8601 date deleted_at string? ISO 8601 date if the comment was deleted; null, otherwise edited_at string? ISO 8601 date if the comment was edited; null, otherwise edited_by_id number? user id of the user that edited the post; null, otherwise id number the ID of the comment legacy_name string? username displayed on legacy comments message string? markdown of the comment’s content message_html string? html version of the comment’s content parent_id number? ID of the comment’s parent pinned boolean Pin status of the comment replies_count number number of replies to the comment updated_at string ISO 8601 date user_id number user ID of the poster votes_count number number of votes
CommentBundle
Comments and related data.
Field Type Description commentable_meta CommentableMeta[] ID of the object the comment is attached to comments Comment[] Array of comments ordered according to sort ; cursor Cursor has_more boolean If there are more comments or replies available has_more_id number? included_comments Comment[] Related comments; e.g. parent comments and nested replies pinned_comments Comment[]? Pinned comments sort string one of the CommentSort types top_level_count number? Number of comments at the top level. Not returned for replies. total number? Total number of comments. Not retuned for replies. user_follow boolean is the current user watching the comment thread? user_votes number[] IDs of the comments in the bundle the current user has upvoted users UserCompact[] array of users related to the comments
CommentSort
Type Sort Fields new created_at (descending), id (descending) old created_at (ascending), id (ascending) top votes_count (descending), created_at (descending), id (descending)
Building cursor for comments listing
The returned response will be for comments after the specified sort fields.
For example, use last loaded comment for the fields value to load more comments. Also make sure to use same sort and parent_id values.
CommentableMeta
Metadata of the object that a comment is attached to.
Field Type Description id number the ID of the object title string display title type string the type of the object url string url of the object
CurrentUserAttributes
An object listing various related permissions and states for the current user, related to the object it is attached to.
BeatmapsetDiscussionPermissions
TODO: needs a better name.
Name Description can_destroy Can delete the discussion. can_reopen Can reopen the discussion. can_moderate_kudosu Can allow or deny kudosu. can_resolve Can resolve the discussion. vote_score Current vote given to the discussion.
ChatChannelUserAttributes
Name Type Description can_message boolean Can send messages to this channel. can_message_error string? Reason messages cannot be sent to this channel last_read_id number message_id of last message read.
Cursor
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.
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
osu!api open beta
Нет аккаунта?
osu!api open beta
I’ve had an API available for a while but until now it has been on a private on-request basis. In order to try and make developing third party services which expand and support osu!, I have added an API key setup and started to document the API.
Documentation will be expanded as I find time to do so! If anyone currently using the API is able to help expand the documentation then please do.
comentarinformal wrote:
Before I spam it with requests that might not exist, is there anything to get user’s information?
(Also, is there anything to login users from this page in other places?)
There is /api/get_user
Gonna write an entry with the information I have about it.
Is there a fair use limit? (e.g. no more than XX requests per day)
For get_user, I suppose there is a mode parameter for getting user information for Taiko, CtB and osu!mania? Or do I have to file an issue in GitHub? Nevermind, I found it, the parameter to add is called «m» I have edited the GitHub wiki.
Oh well. I have some questions:
Are only the beatmap and user endpoints available?
The parameter «since» in /get_beatmap how I need to pass the time on it? UTC or unix timestamp?
Do I need to pass the key on the wiki’s API too?
Edit: What the countX values mean? Number of beatmaps?
comentarinformal wrote:
Before I spam it with requests that might not exist, is there anything to get user’s information?
(Also, is there anything to login users from this page in other places?)
I guess I’ll update my userbar too when I find some time.
Damnae wrote:
I guess I’ll update my userbar too when I find some time.
I registered it for osu!userbar, but I also use it for my «Big ugly white signature», they are not on the same webserver, but it works fine
I belive only you and peppy can see the name you used, too.
(Yes I took my lazyness off, it was not that long to update ^^)
@Repflez: I tried using your API-powered signature and I get something weird.
Since I only aim for SS, I have 100% Accuracy all the time, and the Accuracy display is weird.
(I now know that despite having all-SS records, the note hit count for getting 50s and 100s are still counted all the time )
Winshley wrote:
@Repflez: I tried using your API-powered signature and I get something weird.
Since I only aim for SS, I have 100% Accuracy all the time, and the Accuracy display is weird.
(I now know that despite having all-SS records, the note hit count for getting 50s and 100s are still counted all the time )
So that’s what the CountX values mean. Thanks for that. I already went and changed the accuracy to show a centered «100% Accuracy» if it’s 100. Forget that. I ditched the bar on it and used the extra space for showing the PP.
(I love how the 300 count ended overlaping the border)
Repflez wrote:
So that’s what the CountX values mean. Thanks for that.
Yeah. At first I thought that there was something wrong with the API showing 50s and 100s despite having 100% Accuracy, until I actually calculated all 300s + 100s + 50s = «Total Hits» on our profile.
About the 300 overlap though, it does need some fix:
When you reached 10 millions of 300 hits, the last number is cut off. Cookiezi has 17 millions of 300 hits.
I’m not sure how the level bar breaking happens though. I was thinking that it probably because I don’t have any ranked score on osu!mania?
[Archived] getting osu! api token
Нет аккаунта?
[Archived] getting osu! api token
here is the website I am currently using this for https://osu-api-crap.minecreeper0913.repl.co
well since the project I am using is all python and not javascript I am using a new tab browser to just test it and so far the code I am using is
url = («https://osu.ppy.sh/oauth/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=%s» % (code))
the &code=%s is basically just grabbing the code that has been given back by oauth and using that as the url, when I am testing it though I am actually using my code
Never share your client secret, it’s secret for a reason. I would recommend resetting it ASAP.
Are you just typing that URL into your browser or are you actually sending it as a post request with whatever python code you have? Typing the URL into your browser won’t work.
The token endpoint takes the parameters in the body of the request, not as query parameters. You are also missing some parameters, like redirect_uri and grant_type.
If you are using python’s requests library, you can do something like this:
Might have some syntax errors because I wrote that from memory and didn’t check anything in an IDE or by running it.
You can try without specifying the content type in your headers, it might work without it. Very simply, the content type header describes what type of content or data is being sent. As far as I recall, the server is expecting that content type but I could be wrong.
now starting to realize that I might have done this a bit wrong, this is the first time I have used an API for something so everything I am doing is new to me.
So the first thing that is happening is that you press the login to link your osu API to the website, then it grabs your code and redirects you to the home website with the code in the url for example http://www.website.com/code=j9838r9y82g9438gh8243hg384hg, and it is supposed to use that, but when in testing it just returns favicon.ico, and I don’t know what that is or means so I might have to change my get request, another issue is but how would I make it get that auth code?
I don’t know anything about the project you are working on, so unfortunately I don’t think I can really answer any of the questions you’re asking.
I don’t know what you mean by a favicon being returned and I also don’t know what you are using the handle the backend of your site, so I can’t specifically tell you how to grab the code. Whatever you are using should have some way of getting query parameters from the URL.
Oauth2 is a very standardized and should be nearly the same everywhere that uses it. osu! is no exception. I would highly recommend looking up and reading about the authorization code flow that you are trying to use here. There should be a ton of resources and maybe a few code examples as well.
There might not be any videos specific to osu!’s API, but there are definitely Oauth2 tutorial videos and examples out there in probably every programming language, which is what you are dealing with right now.
For example, here is a video I found after a quick Google search that is using Python. I can’t fully comment on its quality since I just skimmed through it, but the general flow that the creator of the video goes over seems like it will at least cover how OAuth2 works in general, even if it’s not in the context of osu!’s API.
And even if you don’t really like reading, there are still some pretty good resources you can use that might help in addition to watching a video. Like this and this for example. Again, I’ve only skimmed through these, but they also seem to be pretty good.
here is the code I use:
NOTE I did not actually use SECRET as the secret I have it as SECRET because its secret
/rooms//users//rooms//users//rooms//leaderboard
/rooms//playlist//scores
/rooms//playlist//scores//reports
/rooms
/rooms//seasonal-backgrounds
/scores///download
/scores///beatmapsets/search//beatmapsets/lookup
/beatmapsets//friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
Similar to Get User but with authenticated user (token owner) as user id.
Response format
Additionally, statistics_rulesets is included, containing statistics for all rulesets.
Get User Kudosu
Returns kudosu history.
Response format
Get User Scores
This endpoint returns the scores of specified user.
Response format
Array of Score. Following attributes are included in the response object when applicable.
Get User Beatmaps
Returns the beatmaps of specified user.
Type Notes favourite graveyard loved most_played pending Previously unranked ranked Previously ranked_and_approved
Response format
Array of BeatmapPlaycount when type is most_played ; array of Beatmapset, otherwise.
Get User Recent Activity
Returns recent activity.
Response format
Get User
This endpoint returns the detail of specified user.
Response format
Returns User object. The following optional attributes on UserCompact are included:
Get Users
Returns list of users.
Response format
Field Type Description users UserCompact[] Includes: country, cover, groups, statistics_rulesets.
Get Wiki Page
The wiki article or image data.
Response Format
Notification Websocket
Connection
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:
Field Type Description event string See below
logout event
Server will disconnect session after sending this event so don’t try to reconnect.
Field Type Description event string logout
new event
New notification. See Notification object for notification types.
Field Type Description event string new data Notification
read event
Notification has been read.
Field Type Description event string read ids number[] id of Notifications which are read
Object Structures
Beatmap
Represent a beatmap. This extends BeatmapCompact with additional attributes.
Field Type Description accuracy float ar float beatmapset_id integer bpm float? convert boolean count_circles integer count_sliders integer count_spinners integer cs float deleted_at Timestamp? drain float hit_length integer is_scoreable boolean last_updated Timestamp mode_int integer passcount integer playcount integer ranked integer See Rank status for list of possible values. url string
BeatmapCompact
Represent a beatmap.
Field Type Description beatmapset_id integer difficulty_rating float id integer mode GameMode status string See Rank status for list of possible values. total_length integer user_id integer version string
Field Type Description beatmapset Beatmapset|BeatmapsetCompact|null Beatmapset for Beatmap object, BeatmapsetCompact for BeatmapCompact object. null if the beatmap doesn’t have associated beatmapset (e.g. deleted). checksum string? failtimes Failtimes max_combo integer
Failtimes
All fields are optional but there’s always at least one field returned.
Field Type Description exit integer[]? Array of length 100. fail integer[]? Array of length 100.
BeatmapDifficultyAttributes
Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.
Field Type max_combo integer star_rating float
Field Type aim_difficulty float approach_rate float flashlight_difficulty float overall_difficulty float slider_factor float speed_difficulty float
taiko
Field Type stamina_difficulty float rhythm_difficulty float colour_difficulty float approach_rate float great_hit_window float
fruits
mania
Field Type great_hit_window float score_multiplier float
BeatmapPlaycount
Represent the playcount of a beatmap.
Field Type Description beatmap_id number beatmap BeatmapCompact? beatmapset BeatmapsetCompact? count number
BeatmapScores
Field Type Description scores Score[] The list of top scores for the beatmap in descending order. userScore BeatmapUserScore? The score of the current user. This is not returned if the current user does not have a score. Note: will be moved to user_score in the future
BeatmapUserScore
Field Type Description position number The position of the score within the requested beatmap ranking. score Score The details of the score.
Beatmapset
Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.
Field Type Description availability.download_disabled boolean availability.more_information string? bpm float can_be_hyped boolean creator string Username of the mapper at the time of beatmapset creation. discussion_locked boolean hype.current integer hype.required integer is_scoreable boolean last_updated Timestamp legacy_thread_url string? nominations.current integer nominations.required integer ranked integer See Rank status for list of possible values. ranked_date Timestamp? source string storyboard boolean submitted_date Timestamp? tags string
The following attributes are always included as well:
Field has_favourited
BeatmapsetCompact
Represents a beatmapset.
Field Type Description artist string artist_unicode string covers Covers creator string favourite_count number id number nsfw boolean play_count number preview_url string source string status string title string title_unicode string user_id number video boolean
Those fields are optional.
Field Type Description beatmaps Beatmap[] converts current_user_attributes description discussions events genre has_favourited boolean language nominations ratings recent_favourites related_users user
Covers
Field Type cover string cover@2x string card string card@2x string list string list@2x string slimcover string slimcover@2x string
Rank status
The possible values are denoted either as integer or string.
Integer String -2 graveyard -1 wip 0 pending 1 ranked 2 approved 3 qualified 4 loved
BeatmapsetDiscussion
Represents a Beatmapset modding discussion.
Field Type Description beatmap BeatmapCompact? beatmap_id number? beatmapset BeatmapsetCompact? beatmapset_id number can_be_resolved boolean can_grant_kudosu boolean created_at Timestamp current_user_attributes CurrentUserAttributes deleted_at Timestamp? deleted_by_id number? id number kudosu_denied boolean last_post_at Timestamp message_type MessageType parent_id number? posts BeatmapsetDiscussionPost[]? resolved boolean starting_post BeatmapsetDiscussionPost? timestamp number? updated_at Timestamp user_id number
MessageType
Name Description hype mapper_note praise problem review suggestion
BeatmapsetDiscussionPost
Field Type Description beatmapset_discussion_id number created_at Timestamp deleted_at Timestamp? deleted_by_id number? id number last_editor_id number? message string system boolean updated_at Timestamp user_id number
BeatmapsetDiscussionVote
Field Type Description beatmapset_discussion_id number created_at Timestamp id number score number updated_at Timestamp user_id number
Build
Field Type created_at Timestamp display_version string id number update_stream UpdateStream? users number version string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes changelog_entries ChangelogEntry[] If the build has no changelog entries, a placeholder is generated. versions Versions
Versions
ChangelogEntry
Field Type category string created_at Timestamp? github_pull_request_id number? github_url string? id number? major boolean repository string? title string? type string url string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes github_user GithubUser If the changelog entry has no GitHub user, a placeholder is generated. message string? Entry message in Markdown format. Embedded HTML is allowed. message_html string? Entry message in HTML format.
ChatChannel
Represents an individual chat «channel» in the game.
Channel Types
Type Permission Check for Joining/Messaging PUBLIC PRIVATE is player in the allowed groups? (channel.allowed_groups) MULTIPLAYER is player currently in the mp game? SPECTATOR TEMPORARY deprecated PM see below (user_channels) GROUP is player in channel? (user_channels)
For PMs, two factors are taken into account:
ChatMessage
Represents an individual Message within a ChatChannel.
Field Type Description message_id number unique identifier for message sender_id number user_id of the sender channel_id number channel_id of where the message was sent timestamp string when the message was sent, ISO-8601 content string message content is_action boolean was this an action? i.e. /me dances sender UserCompact embedded UserCompact object to save additional api lookups
Comment
Represents an single comment.
Field Type Description commentable_id number ID of the object the comment is attached to commentable_type string type of object the comment is attached to created_at string ISO 8601 date deleted_at string? ISO 8601 date if the comment was deleted; null, otherwise edited_at string? ISO 8601 date if the comment was edited; null, otherwise edited_by_id number? user id of the user that edited the post; null, otherwise id number the ID of the comment legacy_name string? username displayed on legacy comments message string? markdown of the comment’s content message_html string? html version of the comment’s content parent_id number? ID of the comment’s parent pinned boolean Pin status of the comment replies_count number number of replies to the comment updated_at string ISO 8601 date user_id number user ID of the poster votes_count number number of votes
CommentBundle
Comments and related data.
Field Type Description commentable_meta CommentableMeta[] ID of the object the comment is attached to comments Comment[] Array of comments ordered according to sort ; cursor Cursor has_more boolean If there are more comments or replies available has_more_id number? included_comments Comment[] Related comments; e.g. parent comments and nested replies pinned_comments Comment[]? Pinned comments sort string one of the CommentSort types top_level_count number? Number of comments at the top level. Not returned for replies. total number? Total number of comments. Not retuned for replies. user_follow boolean is the current user watching the comment thread? user_votes number[] IDs of the comments in the bundle the current user has upvoted users UserCompact[] array of users related to the comments
CommentSort
Type Sort Fields new created_at (descending), id (descending) old created_at (ascending), id (ascending) top votes_count (descending), created_at (descending), id (descending)
Building cursor for comments listing
The returned response will be for comments after the specified sort fields.
For example, use last loaded comment for the fields value to load more comments. Also make sure to use same sort and parent_id values.
CommentableMeta
Metadata of the object that a comment is attached to.
Field Type Description id number the ID of the object title string display title type string the type of the object url string url of the object
CurrentUserAttributes
An object listing various related permissions and states for the current user, related to the object it is attached to.
BeatmapsetDiscussionPermissions
TODO: needs a better name.
Name Description can_destroy Can delete the discussion. can_reopen Can reopen the discussion. can_moderate_kudosu Can allow or deny kudosu. can_resolve Can resolve the discussion. vote_score Current vote given to the discussion.
ChatChannelUserAttributes
Name Type Description can_message boolean Can send messages to this channel. can_message_error string? Reason messages cannot be sent to this channel last_read_id number message_id of last message read.
Cursor
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.
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
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-07-06
2022-06-08
2021-10-28
2021-09-01
2021-08-11
2021-06-14
2021-06-09
2021-04-20
2021-02-25
2020-09-08
2020-08-28
2020-05-01
2020-02-18
2019-10-09
2019-07-18
Endpoint
Base URL
The base URL is: https://osu.ppy.sh/api/[version]/
API Versions
This is combined with the base endpoint to determine where requests should be sent.
Version Status v2 current (not yet public, consider unstable and expect breaking changes) v1 legacy api provided by the old site, will be deprecated soon
Authentication
Routes marked with the OAuth label require a valid OAuth2 token for access.
More information about applications you have registered and granted permissions to can be found here.
The API supports the following grant types:
Before you can use the osu!api, you will need to
Registering an OAuth application
Before you can get an OAuth token, you will need to register an OAuth application on your account settings page
To register an OAuth application you will need to provide the:
Name Description Application Name This is the name that will be visible to users of your application. The name of your application cannot be changed. Application Callback URL The URL in your application where users will be sent after authorization.
The Application Callback URL is required when for using Authorization Codes. This may be left blank if you are only using Client Credentials Grants.
Your new OAuth application will have a Client ID and Client Secret ; the Client Secret is like a password for your OAuth application, it should be kept private and do not share it with anyone else.
Authorization Code Grant
The flow to authorize users for your application is:
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:
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:
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.
Make sure to replace <> 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:
Name Description chat.write Allows sending chat messages on a user’s behalf. delegate Allows acting as the owner of a client; only available for Client Credentials Grant. forum.write Allows creating and editing forum posts on a user’s behalf. friends.read Allows reading of the user’s friend list. identify Allows reading of the public profile of the user ( /me ). public Allows reading of publicly available data on behalf of the user.
identify is the default scope for the Authorization Code Grant and always implicitly provided. The Client Credentials Grant does not currently have any default scopes.
Routes marked with lazer are intended for use by the osu!lazer client and not currently available for use with Authorization Code or Client Credentials grants.
Using the chat.write scope requires either
Managing OAuth applications
Your account settings page will show your registered OAuth applications, and all the OAuth applications you have granted permissions to.
Reset Client Secret
You can generate a new Client Secret by choosing to «Reset client secret», however, this will disable all access tokens issued for the application.
Beatmaps
Lookup Beatmap
Response format
Get a User Beatmap score
Return a User’s score on a Beatmap
Response Format
The position returned depends on the requested mode and mods.
Get a User Beatmap scores
Return a User’s scores on a Beatmap
Response Format
Get Beatmap scores
Returns the top scores for a beatmap
Response Format
Get Beatmap scores (temp)
Returns the top scores for a beatmap from newer client.
This is a temporary endpoint.
Response Format
Get Beatmaps
Returns list of beatmaps.
Response format
Field Type Description beatmaps BeatmapCompact[] Includes: beatmapset (with ratings), failtimes, max_combo.
Get Beatmap
Gets beatmap data for the specified beatmap ID.
Response format
Returns Beatmap object. Following attributes are included in the response object when applicable,
Attribute Notes beatmapset Includes ratings property. failtimes max_combo
Get Beatmap Attributes
Returns difficulty attributes of beatmap with specific mode and mods combination.
Response format
Beatmapset Discussions
Get Beatmapset Discussion Posts
Returns the posts of beatmapset discussions.
Response Format
Get Beatmapset Discussion Votes
Returns the votes given to beatmapset discussions.
Response Format
Get Beatmapset Discussions
Returns a list of beatmapset discussions.
Response Format
Changelog
Get Changelog Build
Returns details of the specified build.
Response Format
Get Changelog Listing
Returns a listing of update streams, builds, and changelog entries.
Response Format
Lookup Changelog Build
Returns details of the specified build.
Response Format
Create New PM
This endpoint allows you to create a new PM channel.
Response Format
Field Type new_channel_id channel_id of newly created ChatChannel presence array of ChatChannel message the sent ChatMessage
This endpoint will only allow the creation of PMs initially, group chat support will come later.
Get Updates
This endpoint returns new messages since the given message_id along with updated channel ‘presence’ data.
Response Format
Get Channel Messages
This endpoint returns the chat messages for a specific channel.
Response Format
Returns an array of ChatMessage
Send Message to Channel
This endpoint returns the chat messages for a specific channel.
Response Format
Join Channel
This endpoint allows you to join a public or multiplayer channel.
Response Format
Returns the joined ChatChannel.
Leave Channel
This endpoint allows you to leave a public channel.
Response Format
Mark Channel as Read
Response Format
Get Channel List
This endpoint returns a list of all joinable public channels.
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.
Response Format
Returns ChatChannel with recent_messages attribute. Note that in the case of PM s, 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.
Response Format
Field Type Description channel ChatChannel users UserCompact Users are only visible for PM channels.
Comments
Get Comments
Returns a list comments and their replies up to 2 levels deep.
Response Format
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.
Response Format
Get a Comment
Gets a comment and its replies up to 2 levels deep.
Response Format
Edit Comment
Edit an existing comment.
Response Format
Delete Comment
Deletes the specified comment.
Response Format
Add Comment vote
Upvotes a comment.
Response Format
Remove Comment vote
Un-upvotes a comment.
Response Format
Forum
Reply Topic
Create a post replying to the specified topic.
Response Format
ForumPost with body included.
Create Topic
Create a new topic.
Response Format
Get Topic and Posts
Get topic and its posts.
Response Format
Edit Topic
Edit topic. Only title can be edited through this endpoint.
Response Format
Edit Post
Edit specified forum post.
Response Format
ForumPost with body included.
Search
Searches users and wiki pages.
Response Format
SearchResult
Multiplayer
Get User High Score
Returns detail of highest score of specified user and the surrounding scores.
Response Format
Get Scores
Returns a list of scores for specified playlist item.
Response Format
Get a Score
Returns detail of specified score and the surrounding scores.
Response Format
Get News Listing
Returns a list of news posts and related metadata.
Response Format
Get News Post
Returns details of the specified news post.
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.
Response Format
Returns an object containing Notification and other related attributes.
Field Type has_more boolean whether or not there are more notifications notifications array of Notification unread_count total unread notifications notification_endpoint url to connect to websocket server
Mark Notifications as Read
This endpoint allows you to mark notifications read.
Response Format
OAuth Tokens
Revoke current token
Revokes currently authenticated token.
Ranking
Get Ranking
Gets the current ranking for the specified type and game mode.
Response Format
Get Spotlights
Gets the list of spotlights.
Response Format
Undocumented
/beatmaps//solo/scores
/beatmaps//solo/scores//beatmapsets/events
/beatmapsets//favourites
/chat/presence
/matches
/matches//rooms//rooms//users//rooms//users//rooms//leaderboard
/rooms//playlist//scores
/rooms//playlist//scores//reports
/rooms
/rooms//seasonal-backgrounds
/scores///download
/scores///beatmapsets/search//beatmapsets/lookup
/beatmapsets//friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
Similar to Get User but with authenticated user (token owner) as user id.
Response format
Additionally, statistics_rulesets is included, containing statistics for all rulesets.
Get User Kudosu
Returns kudosu history.
Response format
Get User Scores
This endpoint returns the scores of specified user.
Response format
Array of Score. Following attributes are included in the response object when applicable.
Get User Beatmaps
Returns the beatmaps of specified user.
Type Notes favourite graveyard loved most_played pending Previously unranked ranked Previously ranked_and_approved
Response format
Array of BeatmapPlaycount when type is most_played ; array of Beatmapset, otherwise.
Get User Recent Activity
Returns recent activity.
Response format
Get User
This endpoint returns the detail of specified user.
Response format
Returns User object. The following optional attributes on UserCompact are included:
Get Users
Returns list of users.
Response format
Field Type Description users UserCompact[] Includes: country, cover, groups, statistics_rulesets.
Get Wiki Page
The wiki article or image data.
Response Format
Notification Websocket
Connection
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:
Field Type Description event string See below
logout event
Server will disconnect session after sending this event so don’t try to reconnect.
Field Type Description event string logout
new event
New notification. See Notification object for notification types.
Field Type Description event string new data Notification
read event
Notification has been read.
Field Type Description event string read ids number[] id of Notifications which are read
Object Structures
Beatmap
Represent a beatmap. This extends BeatmapCompact with additional attributes.
Field Type Description accuracy float ar float beatmapset_id integer bpm float? convert boolean count_circles integer count_sliders integer count_spinners integer cs float deleted_at Timestamp? drain float hit_length integer is_scoreable boolean last_updated Timestamp mode_int integer passcount integer playcount integer ranked integer See Rank status for list of possible values. url string
BeatmapCompact
Represent a beatmap.
Field Type Description beatmapset_id integer difficulty_rating float id integer mode GameMode status string See Rank status for list of possible values. total_length integer user_id integer version string
Field Type Description beatmapset Beatmapset|BeatmapsetCompact|null Beatmapset for Beatmap object, BeatmapsetCompact for BeatmapCompact object. null if the beatmap doesn’t have associated beatmapset (e.g. deleted). checksum string? failtimes Failtimes max_combo integer
Failtimes
All fields are optional but there’s always at least one field returned.
Field Type Description exit integer[]? Array of length 100. fail integer[]? Array of length 100.
BeatmapDifficultyAttributes
Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.
Field Type max_combo integer star_rating float
Field Type aim_difficulty float approach_rate float flashlight_difficulty float overall_difficulty float slider_factor float speed_difficulty float
taiko
Field Type stamina_difficulty float rhythm_difficulty float colour_difficulty float approach_rate float great_hit_window float
fruits
mania
Field Type great_hit_window float score_multiplier float
BeatmapPlaycount
Represent the playcount of a beatmap.
Field Type Description beatmap_id number beatmap BeatmapCompact? beatmapset BeatmapsetCompact? count number
BeatmapScores
Field Type Description scores Score[] The list of top scores for the beatmap in descending order. userScore BeatmapUserScore? The score of the current user. This is not returned if the current user does not have a score. Note: will be moved to user_score in the future
BeatmapUserScore
Field Type Description position number The position of the score within the requested beatmap ranking. score Score The details of the score.
Beatmapset
Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.
Field Type Description availability.download_disabled boolean availability.more_information string? bpm float can_be_hyped boolean creator string Username of the mapper at the time of beatmapset creation. discussion_locked boolean hype.current integer hype.required integer is_scoreable boolean last_updated Timestamp legacy_thread_url string? nominations.current integer nominations.required integer ranked integer See Rank status for list of possible values. ranked_date Timestamp? source string storyboard boolean submitted_date Timestamp? tags string
The following attributes are always included as well:
Field has_favourited
BeatmapsetCompact
Represents a beatmapset.
Field Type Description artist string artist_unicode string covers Covers creator string favourite_count number id number nsfw boolean play_count number preview_url string source string status string title string title_unicode string user_id number video boolean
Those fields are optional.
Field Type Description beatmaps Beatmap[] converts current_user_attributes description discussions events genre has_favourited boolean language nominations ratings recent_favourites related_users user
Covers
Field Type cover string cover@2x string card string card@2x string list string list@2x string slimcover string slimcover@2x string
Rank status
The possible values are denoted either as integer or string.
Integer String -2 graveyard -1 wip 0 pending 1 ranked 2 approved 3 qualified 4 loved
BeatmapsetDiscussion
Represents a Beatmapset modding discussion.
Field Type Description beatmap BeatmapCompact? beatmap_id number? beatmapset BeatmapsetCompact? beatmapset_id number can_be_resolved boolean can_grant_kudosu boolean created_at Timestamp current_user_attributes CurrentUserAttributes deleted_at Timestamp? deleted_by_id number? id number kudosu_denied boolean last_post_at Timestamp message_type MessageType parent_id number? posts BeatmapsetDiscussionPost[]? resolved boolean starting_post BeatmapsetDiscussionPost? timestamp number? updated_at Timestamp user_id number
MessageType
Name Description hype mapper_note praise problem review suggestion
BeatmapsetDiscussionPost
Field Type Description beatmapset_discussion_id number created_at Timestamp deleted_at Timestamp? deleted_by_id number? id number last_editor_id number? message string system boolean updated_at Timestamp user_id number
BeatmapsetDiscussionVote
Field Type Description beatmapset_discussion_id number created_at Timestamp id number score number updated_at Timestamp user_id number
Build
Field Type created_at Timestamp display_version string id number update_stream UpdateStream? users number version string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes changelog_entries ChangelogEntry[] If the build has no changelog entries, a placeholder is generated. versions Versions
Versions
ChangelogEntry
Field Type category string created_at Timestamp? github_pull_request_id number? github_url string? id number? major boolean repository string? title string? type string url string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes github_user GithubUser If the changelog entry has no GitHub user, a placeholder is generated. message string? Entry message in Markdown format. Embedded HTML is allowed. message_html string? Entry message in HTML format.
ChatChannel
Represents an individual chat «channel» in the game.
Channel Types
Type Permission Check for Joining/Messaging PUBLIC PRIVATE is player in the allowed groups? (channel.allowed_groups) MULTIPLAYER is player currently in the mp game? SPECTATOR TEMPORARY deprecated PM see below (user_channels) GROUP is player in channel? (user_channels)
For PMs, two factors are taken into account:
ChatMessage
Represents an individual Message within a ChatChannel.
Field Type Description message_id number unique identifier for message sender_id number user_id of the sender channel_id number channel_id of where the message was sent timestamp string when the message was sent, ISO-8601 content string message content is_action boolean was this an action? i.e. /me dances sender UserCompact embedded UserCompact object to save additional api lookups
Comment
Represents an single comment.
Field Type Description commentable_id number ID of the object the comment is attached to commentable_type string type of object the comment is attached to created_at string ISO 8601 date deleted_at string? ISO 8601 date if the comment was deleted; null, otherwise edited_at string? ISO 8601 date if the comment was edited; null, otherwise edited_by_id number? user id of the user that edited the post; null, otherwise id number the ID of the comment legacy_name string? username displayed on legacy comments message string? markdown of the comment’s content message_html string? html version of the comment’s content parent_id number? ID of the comment’s parent pinned boolean Pin status of the comment replies_count number number of replies to the comment updated_at string ISO 8601 date user_id number user ID of the poster votes_count number number of votes
CommentBundle
Comments and related data.
Field Type Description commentable_meta CommentableMeta[] ID of the object the comment is attached to comments Comment[] Array of comments ordered according to sort ; cursor Cursor has_more boolean If there are more comments or replies available has_more_id number? included_comments Comment[] Related comments; e.g. parent comments and nested replies pinned_comments Comment[]? Pinned comments sort string one of the CommentSort types top_level_count number? Number of comments at the top level. Not returned for replies. total number? Total number of comments. Not retuned for replies. user_follow boolean is the current user watching the comment thread? user_votes number[] IDs of the comments in the bundle the current user has upvoted users UserCompact[] array of users related to the comments
CommentSort
Type Sort Fields new created_at (descending), id (descending) old created_at (ascending), id (ascending) top votes_count (descending), created_at (descending), id (descending)
Building cursor for comments listing
The returned response will be for comments after the specified sort fields.
For example, use last loaded comment for the fields value to load more comments. Also make sure to use same sort and parent_id values.
CommentableMeta
Metadata of the object that a comment is attached to.
Field Type Description id number the ID of the object title string display title type string the type of the object url string url of the object
CurrentUserAttributes
An object listing various related permissions and states for the current user, related to the object it is attached to.
BeatmapsetDiscussionPermissions
TODO: needs a better name.
Name Description can_destroy Can delete the discussion. can_reopen Can reopen the discussion. can_moderate_kudosu Can allow or deny kudosu. can_resolve Can resolve the discussion. vote_score Current vote given to the discussion.
ChatChannelUserAttributes
Name Type Description can_message boolean Can send messages to this channel. can_message_error string? Reason messages cannot be sent to this channel last_read_id number message_id of last message read.
Cursor
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.
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
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-07-06
2022-06-08
2021-10-28
2021-09-01
2021-08-11
2021-06-14
2021-06-09
2021-04-20
2021-02-25
2020-09-08
2020-08-28
2020-05-01
2020-02-18
2019-10-09
2019-07-18
Endpoint
Base URL
The base URL is: https://osu.ppy.sh/api/[version]/
API Versions
This is combined with the base endpoint to determine where requests should be sent.
Version Status v2 current (not yet public, consider unstable and expect breaking changes) v1 legacy api provided by the old site, will be deprecated soon
Authentication
Routes marked with the OAuth label require a valid OAuth2 token for access.
More information about applications you have registered and granted permissions to can be found here.
The API supports the following grant types:
Before you can use the osu!api, you will need to
Registering an OAuth application
Before you can get an OAuth token, you will need to register an OAuth application on your account settings page
To register an OAuth application you will need to provide the:
Name Description Application Name This is the name that will be visible to users of your application. The name of your application cannot be changed. Application Callback URL The URL in your application where users will be sent after authorization.
The Application Callback URL is required when for using Authorization Codes. This may be left blank if you are only using Client Credentials Grants.
Your new OAuth application will have a Client ID and Client Secret ; the Client Secret is like a password for your OAuth application, it should be kept private and do not share it with anyone else.
Authorization Code Grant
The flow to authorize users for your application is:
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:
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:
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.
Make sure to replace <> 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:
Name Description chat.write Allows sending chat messages on a user’s behalf. delegate Allows acting as the owner of a client; only available for Client Credentials Grant. forum.write Allows creating and editing forum posts on a user’s behalf. friends.read Allows reading of the user’s friend list. identify Allows reading of the public profile of the user ( /me ). public Allows reading of publicly available data on behalf of the user.
identify is the default scope for the Authorization Code Grant and always implicitly provided. The Client Credentials Grant does not currently have any default scopes.
Routes marked with lazer are intended for use by the osu!lazer client and not currently available for use with Authorization Code or Client Credentials grants.
Using the chat.write scope requires either
Managing OAuth applications
Your account settings page will show your registered OAuth applications, and all the OAuth applications you have granted permissions to.
Reset Client Secret
You can generate a new Client Secret by choosing to «Reset client secret», however, this will disable all access tokens issued for the application.
Beatmaps
Lookup Beatmap
Response format
Get a User Beatmap score
Return a User’s score on a Beatmap
Response Format
The position returned depends on the requested mode and mods.
Get a User Beatmap scores
Return a User’s scores on a Beatmap
Response Format
Get Beatmap scores
Returns the top scores for a beatmap
Response Format
Get Beatmap scores (temp)
Returns the top scores for a beatmap from newer client.
This is a temporary endpoint.
Response Format
Get Beatmaps
Returns list of beatmaps.
Response format
Field Type Description beatmaps BeatmapCompact[] Includes: beatmapset (with ratings), failtimes, max_combo.
Get Beatmap
Gets beatmap data for the specified beatmap ID.
Response format
Returns Beatmap object. Following attributes are included in the response object when applicable,
Attribute Notes beatmapset Includes ratings property. failtimes max_combo
Get Beatmap Attributes
Returns difficulty attributes of beatmap with specific mode and mods combination.
Response format
Beatmapset Discussions
Get Beatmapset Discussion Posts
Returns the posts of beatmapset discussions.
Response Format
Get Beatmapset Discussion Votes
Returns the votes given to beatmapset discussions.
Response Format
Get Beatmapset Discussions
Returns a list of beatmapset discussions.
Response Format
Changelog
Get Changelog Build
Returns details of the specified build.
Response Format
Get Changelog Listing
Returns a listing of update streams, builds, and changelog entries.
Response Format
Lookup Changelog Build
Returns details of the specified build.
Response Format
Create New PM
This endpoint allows you to create a new PM channel.
Response Format
Field Type new_channel_id channel_id of newly created ChatChannel presence array of ChatChannel message the sent ChatMessage
This endpoint will only allow the creation of PMs initially, group chat support will come later.
Get Updates
This endpoint returns new messages since the given message_id along with updated channel ‘presence’ data.
Response Format
Get Channel Messages
This endpoint returns the chat messages for a specific channel.
Response Format
Returns an array of ChatMessage
Send Message to Channel
This endpoint returns the chat messages for a specific channel.
Response Format
Join Channel
This endpoint allows you to join a public or multiplayer channel.
Response Format
Returns the joined ChatChannel.
Leave Channel
This endpoint allows you to leave a public channel.
Response Format
Mark Channel as Read
Response Format
Get Channel List
This endpoint returns a list of all joinable public channels.
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.
Response Format
Returns ChatChannel with recent_messages attribute. Note that in the case of PM s, 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.
Response Format
Field Type Description channel ChatChannel users UserCompact Users are only visible for PM channels.
Comments
Get Comments
Returns a list comments and their replies up to 2 levels deep.
Response Format
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.
Response Format
Get a Comment
Gets a comment and its replies up to 2 levels deep.
Response Format
Edit Comment
Edit an existing comment.
Response Format
Delete Comment
Deletes the specified comment.
Response Format
Add Comment vote
Upvotes a comment.
Response Format
Remove Comment vote
Un-upvotes a comment.
Response Format
Forum
Reply Topic
Create a post replying to the specified topic.
Response Format
ForumPost with body included.
Create Topic
Create a new topic.
Response Format
Get Topic and Posts
Get topic and its posts.
Response Format
Edit Topic
Edit topic. Only title can be edited through this endpoint.
Response Format
Edit Post
Edit specified forum post.
Response Format
ForumPost with body included.
Search
Searches users and wiki pages.
Response Format
SearchResult
Multiplayer
Get User High Score
Returns detail of highest score of specified user and the surrounding scores.
Response Format
Get Scores
Returns a list of scores for specified playlist item.
Response Format
Get a Score
Returns detail of specified score and the surrounding scores.
Response Format
Get News Listing
Returns a list of news posts and related metadata.
Response Format
Get News Post
Returns details of the specified news post.
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.
Response Format
Returns an object containing Notification and other related attributes.
Field Type has_more boolean whether or not there are more notifications notifications array of Notification unread_count total unread notifications notification_endpoint url to connect to websocket server
Mark Notifications as Read
This endpoint allows you to mark notifications read.
Response Format
OAuth Tokens
Revoke current token
Revokes currently authenticated token.
Ranking
Get Ranking
Gets the current ranking for the specified type and game mode.
Response Format
Get Spotlights
Gets the list of spotlights.
Response Format
Undocumented
/beatmaps//solo/scores
/beatmaps//solo/scores//beatmapsets/events
/beatmapsets//favourites
/chat/presence
/matches
/matches//rooms//rooms//users//rooms//users//rooms//leaderboard
/rooms//playlist//scores
/rooms//playlist//scores//reports
/rooms
/rooms//seasonal-backgrounds
/scores///download
/scores///beatmapsets/search//beatmapsets/lookup
/beatmapsets//friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
Similar to Get User but with authenticated user (token owner) as user id.
Response format
Additionally, statistics_rulesets is included, containing statistics for all rulesets.
Get User Kudosu
Returns kudosu history.
Response format
Get User Scores
This endpoint returns the scores of specified user.
Response format
Array of Score. Following attributes are included in the response object when applicable.
Get User Beatmaps
Returns the beatmaps of specified user.
Type Notes favourite graveyard loved most_played pending Previously unranked ranked Previously ranked_and_approved
Response format
Array of BeatmapPlaycount when type is most_played ; array of Beatmapset, otherwise.
Get User Recent Activity
Returns recent activity.
Response format
Get User
This endpoint returns the detail of specified user.
Response format
Returns User object. The following optional attributes on UserCompact are included:
Get Users
Returns list of users.
Response format
Field Type Description users UserCompact[] Includes: country, cover, groups, statistics_rulesets.
Get Wiki Page
The wiki article or image data.
Response Format
Notification Websocket
Connection
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:
Field Type Description event string See below
logout event
Server will disconnect session after sending this event so don’t try to reconnect.
Field Type Description event string logout
new event
New notification. See Notification object for notification types.
Field Type Description event string new data Notification
read event
Notification has been read.
Field Type Description event string read ids number[] id of Notifications which are read
Object Structures
Beatmap
Represent a beatmap. This extends BeatmapCompact with additional attributes.
Field Type Description accuracy float ar float beatmapset_id integer bpm float? convert boolean count_circles integer count_sliders integer count_spinners integer cs float deleted_at Timestamp? drain float hit_length integer is_scoreable boolean last_updated Timestamp mode_int integer passcount integer playcount integer ranked integer See Rank status for list of possible values. url string
BeatmapCompact
Represent a beatmap.
Field Type Description beatmapset_id integer difficulty_rating float id integer mode GameMode status string See Rank status for list of possible values. total_length integer user_id integer version string
Field Type Description beatmapset Beatmapset|BeatmapsetCompact|null Beatmapset for Beatmap object, BeatmapsetCompact for BeatmapCompact object. null if the beatmap doesn’t have associated beatmapset (e.g. deleted). checksum string? failtimes Failtimes max_combo integer
Failtimes
All fields are optional but there’s always at least one field returned.
Field Type Description exit integer[]? Array of length 100. fail integer[]? Array of length 100.
BeatmapDifficultyAttributes
Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.
Field Type max_combo integer star_rating float
Field Type aim_difficulty float approach_rate float flashlight_difficulty float overall_difficulty float slider_factor float speed_difficulty float
taiko
Field Type stamina_difficulty float rhythm_difficulty float colour_difficulty float approach_rate float great_hit_window float
fruits
mania
Field Type great_hit_window float score_multiplier float
BeatmapPlaycount
Represent the playcount of a beatmap.
Field Type Description beatmap_id number beatmap BeatmapCompact? beatmapset BeatmapsetCompact? count number
BeatmapScores
Field Type Description scores Score[] The list of top scores for the beatmap in descending order. userScore BeatmapUserScore? The score of the current user. This is not returned if the current user does not have a score. Note: will be moved to user_score in the future
BeatmapUserScore
Field Type Description position number The position of the score within the requested beatmap ranking. score Score The details of the score.
Beatmapset
Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.
Field Type Description availability.download_disabled boolean availability.more_information string? bpm float can_be_hyped boolean creator string Username of the mapper at the time of beatmapset creation. discussion_locked boolean hype.current integer hype.required integer is_scoreable boolean last_updated Timestamp legacy_thread_url string? nominations.current integer nominations.required integer ranked integer See Rank status for list of possible values. ranked_date Timestamp? source string storyboard boolean submitted_date Timestamp? tags string
The following attributes are always included as well:
Field has_favourited
BeatmapsetCompact
Represents a beatmapset.
Field Type Description artist string artist_unicode string covers Covers creator string favourite_count number id number nsfw boolean play_count number preview_url string source string status string title string title_unicode string user_id number video boolean
Those fields are optional.
Field Type Description beatmaps Beatmap[] converts current_user_attributes description discussions events genre has_favourited boolean language nominations ratings recent_favourites related_users user
Covers
Field Type cover string cover@2x string card string card@2x string list string list@2x string slimcover string slimcover@2x string
Rank status
The possible values are denoted either as integer or string.
Integer String -2 graveyard -1 wip 0 pending 1 ranked 2 approved 3 qualified 4 loved
BeatmapsetDiscussion
Represents a Beatmapset modding discussion.
Field Type Description beatmap BeatmapCompact? beatmap_id number? beatmapset BeatmapsetCompact? beatmapset_id number can_be_resolved boolean can_grant_kudosu boolean created_at Timestamp current_user_attributes CurrentUserAttributes deleted_at Timestamp? deleted_by_id number? id number kudosu_denied boolean last_post_at Timestamp message_type MessageType parent_id number? posts BeatmapsetDiscussionPost[]? resolved boolean starting_post BeatmapsetDiscussionPost? timestamp number? updated_at Timestamp user_id number
MessageType
Name Description hype mapper_note praise problem review suggestion
BeatmapsetDiscussionPost
Field Type Description beatmapset_discussion_id number created_at Timestamp deleted_at Timestamp? deleted_by_id number? id number last_editor_id number? message string system boolean updated_at Timestamp user_id number
BeatmapsetDiscussionVote
Field Type Description beatmapset_discussion_id number created_at Timestamp id number score number updated_at Timestamp user_id number
Build
Field Type created_at Timestamp display_version string id number update_stream UpdateStream? users number version string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes changelog_entries ChangelogEntry[] If the build has no changelog entries, a placeholder is generated. versions Versions
Versions
ChangelogEntry
Field Type category string created_at Timestamp? github_pull_request_id number? github_url string? id number? major boolean repository string? title string? type string url string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes github_user GithubUser If the changelog entry has no GitHub user, a placeholder is generated. message string? Entry message in Markdown format. Embedded HTML is allowed. message_html string? Entry message in HTML format.
ChatChannel
Represents an individual chat «channel» in the game.
Channel Types
Type Permission Check for Joining/Messaging PUBLIC PRIVATE is player in the allowed groups? (channel.allowed_groups) MULTIPLAYER is player currently in the mp game? SPECTATOR TEMPORARY deprecated PM see below (user_channels) GROUP is player in channel? (user_channels)
For PMs, two factors are taken into account:
ChatMessage
Represents an individual Message within a ChatChannel.
Field Type Description message_id number unique identifier for message sender_id number user_id of the sender channel_id number channel_id of where the message was sent timestamp string when the message was sent, ISO-8601 content string message content is_action boolean was this an action? i.e. /me dances sender UserCompact embedded UserCompact object to save additional api lookups
Comment
Represents an single comment.
Field Type Description commentable_id number ID of the object the comment is attached to commentable_type string type of object the comment is attached to created_at string ISO 8601 date deleted_at string? ISO 8601 date if the comment was deleted; null, otherwise edited_at string? ISO 8601 date if the comment was edited; null, otherwise edited_by_id number? user id of the user that edited the post; null, otherwise id number the ID of the comment legacy_name string? username displayed on legacy comments message string? markdown of the comment’s content message_html string? html version of the comment’s content parent_id number? ID of the comment’s parent pinned boolean Pin status of the comment replies_count number number of replies to the comment updated_at string ISO 8601 date user_id number user ID of the poster votes_count number number of votes
CommentBundle
Comments and related data.
Field Type Description commentable_meta CommentableMeta[] ID of the object the comment is attached to comments Comment[] Array of comments ordered according to sort ; cursor Cursor has_more boolean If there are more comments or replies available has_more_id number? included_comments Comment[] Related comments; e.g. parent comments and nested replies pinned_comments Comment[]? Pinned comments sort string one of the CommentSort types top_level_count number? Number of comments at the top level. Not returned for replies. total number? Total number of comments. Not retuned for replies. user_follow boolean is the current user watching the comment thread? user_votes number[] IDs of the comments in the bundle the current user has upvoted users UserCompact[] array of users related to the comments
CommentSort
Type Sort Fields new created_at (descending), id (descending) old created_at (ascending), id (ascending) top votes_count (descending), created_at (descending), id (descending)
Building cursor for comments listing
The returned response will be for comments after the specified sort fields.
For example, use last loaded comment for the fields value to load more comments. Also make sure to use same sort and parent_id values.
CommentableMeta
Metadata of the object that a comment is attached to.
Field Type Description id number the ID of the object title string display title type string the type of the object url string url of the object
CurrentUserAttributes
An object listing various related permissions and states for the current user, related to the object it is attached to.
BeatmapsetDiscussionPermissions
TODO: needs a better name.
Name Description can_destroy Can delete the discussion. can_reopen Can reopen the discussion. can_moderate_kudosu Can allow or deny kudosu. can_resolve Can resolve the discussion. vote_score Current vote given to the discussion.
ChatChannelUserAttributes
Name Type Description can_message boolean Can send messages to this channel. can_message_error string? Reason messages cannot be sent to this channel last_read_id number message_id of last message read.
Cursor
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.
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
osu!api open beta
Нет аккаунта?
osu!api open beta
I’ve had an API available for a while but until now it has been on a private on-request basis. In order to try and make developing third party services which expand and support osu!, I have added an API key setup and started to document the API.
Documentation will be expanded as I find time to do so! If anyone currently using the API is able to help expand the documentation then please do.
comentarinformal wrote:
Before I spam it with requests that might not exist, is there anything to get user’s information?
(Also, is there anything to login users from this page in other places?)
There is /api/get_user
Gonna write an entry with the information I have about it.
Is there a fair use limit? (e.g. no more than XX requests per day)
For get_user, I suppose there is a mode parameter for getting user information for Taiko, CtB and osu!mania? Or do I have to file an issue in GitHub? Nevermind, I found it, the parameter to add is called «m» I have edited the GitHub wiki.
Oh well. I have some questions:
Are only the beatmap and user endpoints available?
The parameter «since» in /get_beatmap how I need to pass the time on it? UTC or unix timestamp?
Do I need to pass the key on the wiki’s API too?
Edit: What the countX values mean? Number of beatmaps?
comentarinformal wrote:
Before I spam it with requests that might not exist, is there anything to get user’s information?
(Also, is there anything to login users from this page in other places?)
I guess I’ll update my userbar too when I find some time.
Damnae wrote:
I guess I’ll update my userbar too when I find some time.
I registered it for osu!userbar, but I also use it for my «Big ugly white signature», they are not on the same webserver, but it works fine
I belive only you and peppy can see the name you used, too.
(Yes I took my lazyness off, it was not that long to update ^^)
@Repflez: I tried using your API-powered signature and I get something weird.
Since I only aim for SS, I have 100% Accuracy all the time, and the Accuracy display is weird.
(I now know that despite having all-SS records, the note hit count for getting 50s and 100s are still counted all the time )
Winshley wrote:
@Repflez: I tried using your API-powered signature and I get something weird.
Since I only aim for SS, I have 100% Accuracy all the time, and the Accuracy display is weird.
(I now know that despite having all-SS records, the note hit count for getting 50s and 100s are still counted all the time )
So that’s what the CountX values mean. Thanks for that. I already went and changed the accuracy to show a centered «100% Accuracy» if it’s 100. Forget that. I ditched the bar on it and used the extra space for showing the PP.
(I love how the 300 count ended overlaping the border)
Repflez wrote:
So that’s what the CountX values mean. Thanks for that.
Yeah. At first I thought that there was something wrong with the API showing 50s and 100s despite having 100% Accuracy, until I actually calculated all 300s + 100s + 50s = «Total Hits» on our profile.
About the 300 overlap though, it does need some fix:
When you reached 10 millions of 300 hits, the last number is cut off. Cookiezi has 17 millions of 300 hits.
I’m not sure how the level bar breaking happens though. I was thinking that it probably because I don’t have any ranked score on osu!mania?
[Archived] getting osu! api token
Нет аккаунта?
[Archived] getting osu! api token
here is the website I am currently using this for https://osu-api-crap.minecreeper0913.repl.co
well since the project I am using is all python and not javascript I am using a new tab browser to just test it and so far the code I am using is
url = («https://osu.ppy.sh/oauth/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=%s» % (code))
the &code=%s is basically just grabbing the code that has been given back by oauth and using that as the url, when I am testing it though I am actually using my code
Never share your client secret, it’s secret for a reason. I would recommend resetting it ASAP.
Are you just typing that URL into your browser or are you actually sending it as a post request with whatever python code you have? Typing the URL into your browser won’t work.
The token endpoint takes the parameters in the body of the request, not as query parameters. You are also missing some parameters, like redirect_uri and grant_type.
If you are using python’s requests library, you can do something like this:
Might have some syntax errors because I wrote that from memory and didn’t check anything in an IDE or by running it.
You can try without specifying the content type in your headers, it might work without it. Very simply, the content type header describes what type of content or data is being sent. As far as I recall, the server is expecting that content type but I could be wrong.
now starting to realize that I might have done this a bit wrong, this is the first time I have used an API for something so everything I am doing is new to me.
So the first thing that is happening is that you press the login to link your osu API to the website, then it grabs your code and redirects you to the home website with the code in the url for example http://www.website.com/code=j9838r9y82g9438gh8243hg384hg, and it is supposed to use that, but when in testing it just returns favicon.ico, and I don’t know what that is or means so I might have to change my get request, another issue is but how would I make it get that auth code?
I don’t know anything about the project you are working on, so unfortunately I don’t think I can really answer any of the questions you’re asking.
I don’t know what you mean by a favicon being returned and I also don’t know what you are using the handle the backend of your site, so I can’t specifically tell you how to grab the code. Whatever you are using should have some way of getting query parameters from the URL.
Oauth2 is a very standardized and should be nearly the same everywhere that uses it. osu! is no exception. I would highly recommend looking up and reading about the authorization code flow that you are trying to use here. There should be a ton of resources and maybe a few code examples as well.
There might not be any videos specific to osu!’s API, but there are definitely Oauth2 tutorial videos and examples out there in probably every programming language, which is what you are dealing with right now.
For example, here is a video I found after a quick Google search that is using Python. I can’t fully comment on its quality since I just skimmed through it, but the general flow that the creator of the video goes over seems like it will at least cover how OAuth2 works in general, even if it’s not in the context of osu!’s API.
And even if you don’t really like reading, there are still some pretty good resources you can use that might help in addition to watching a video. Like this and this for example. Again, I’ve only skimmed through these, but they also seem to be pretty good.
here is the code I use:
NOTE I did not actually use SECRET as the secret I have it as SECRET because its secret
/rooms//users//rooms//leaderboard
/rooms//playlist//scores
/rooms//playlist//scores//reports
/rooms
/rooms//seasonal-backgrounds
/scores///download
/scores///beatmapsets/search//beatmapsets/lookup
/beatmapsets//friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
Similar to Get User but with authenticated user (token owner) as user id.
Response format
Additionally, statistics_rulesets is included, containing statistics for all rulesets.
Get User Kudosu
Returns kudosu history.
Response format
Get User Scores
This endpoint returns the scores of specified user.
Response format
Array of Score. Following attributes are included in the response object when applicable.
Get User Beatmaps
Returns the beatmaps of specified user.
Type Notes favourite graveyard loved most_played pending Previously unranked ranked Previously ranked_and_approved
Response format
Array of BeatmapPlaycount when type is most_played ; array of Beatmapset, otherwise.
Get User Recent Activity
Returns recent activity.
Response format
Get User
This endpoint returns the detail of specified user.
Response format
Returns User object. The following optional attributes on UserCompact are included:
Get Users
Returns list of users.
Response format
Field Type Description users UserCompact[] Includes: country, cover, groups, statistics_rulesets.
Get Wiki Page
The wiki article or image data.
Response Format
Notification Websocket
Connection
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:
Field Type Description event string See below
logout event
Server will disconnect session after sending this event so don’t try to reconnect.
Field Type Description event string logout
new event
New notification. See Notification object for notification types.
Field Type Description event string new data Notification
read event
Notification has been read.
Field Type Description event string read ids number[] id of Notifications which are read
Object Structures
Beatmap
Represent a beatmap. This extends BeatmapCompact with additional attributes.
Field Type Description accuracy float ar float beatmapset_id integer bpm float? convert boolean count_circles integer count_sliders integer count_spinners integer cs float deleted_at Timestamp? drain float hit_length integer is_scoreable boolean last_updated Timestamp mode_int integer passcount integer playcount integer ranked integer See Rank status for list of possible values. url string
BeatmapCompact
Represent a beatmap.
Field Type Description beatmapset_id integer difficulty_rating float id integer mode GameMode status string See Rank status for list of possible values. total_length integer user_id integer version string
Field Type Description beatmapset Beatmapset|BeatmapsetCompact|null Beatmapset for Beatmap object, BeatmapsetCompact for BeatmapCompact object. null if the beatmap doesn’t have associated beatmapset (e.g. deleted). checksum string? failtimes Failtimes max_combo integer
Failtimes
All fields are optional but there’s always at least one field returned.
Field Type Description exit integer[]? Array of length 100. fail integer[]? Array of length 100.
BeatmapDifficultyAttributes
Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.
Field Type max_combo integer star_rating float
Field Type aim_difficulty float approach_rate float flashlight_difficulty float overall_difficulty float slider_factor float speed_difficulty float
taiko
Field Type stamina_difficulty float rhythm_difficulty float colour_difficulty float approach_rate float great_hit_window float
fruits
mania
Field Type great_hit_window float score_multiplier float
BeatmapPlaycount
Represent the playcount of a beatmap.
Field Type Description beatmap_id number beatmap BeatmapCompact? beatmapset BeatmapsetCompact? count number
BeatmapScores
Field Type Description scores Score[] The list of top scores for the beatmap in descending order. userScore BeatmapUserScore? The score of the current user. This is not returned if the current user does not have a score. Note: will be moved to user_score in the future
BeatmapUserScore
Field Type Description position number The position of the score within the requested beatmap ranking. score Score The details of the score.
Beatmapset
Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.
Field Type Description availability.download_disabled boolean availability.more_information string? bpm float can_be_hyped boolean creator string Username of the mapper at the time of beatmapset creation. discussion_locked boolean hype.current integer hype.required integer is_scoreable boolean last_updated Timestamp legacy_thread_url string? nominations.current integer nominations.required integer ranked integer See Rank status for list of possible values. ranked_date Timestamp? source string storyboard boolean submitted_date Timestamp? tags string
The following attributes are always included as well:
Field has_favourited
BeatmapsetCompact
Represents a beatmapset.
Field Type Description artist string artist_unicode string covers Covers creator string favourite_count number id number nsfw boolean play_count number preview_url string source string status string title string title_unicode string user_id number video boolean
Those fields are optional.
Field Type Description beatmaps Beatmap[] converts current_user_attributes description discussions events genre has_favourited boolean language nominations ratings recent_favourites related_users user
Covers
Field Type cover string cover@2x string card string card@2x string list string list@2x string slimcover string slimcover@2x string
Rank status
The possible values are denoted either as integer or string.
Integer String -2 graveyard -1 wip 0 pending 1 ranked 2 approved 3 qualified 4 loved
BeatmapsetDiscussion
Represents a Beatmapset modding discussion.
Field Type Description beatmap BeatmapCompact? beatmap_id number? beatmapset BeatmapsetCompact? beatmapset_id number can_be_resolved boolean can_grant_kudosu boolean created_at Timestamp current_user_attributes CurrentUserAttributes deleted_at Timestamp? deleted_by_id number? id number kudosu_denied boolean last_post_at Timestamp message_type MessageType parent_id number? posts BeatmapsetDiscussionPost[]? resolved boolean starting_post BeatmapsetDiscussionPost? timestamp number? updated_at Timestamp user_id number
MessageType
Name Description hype mapper_note praise problem review suggestion
BeatmapsetDiscussionPost
Field Type Description beatmapset_discussion_id number created_at Timestamp deleted_at Timestamp? deleted_by_id number? id number last_editor_id number? message string system boolean updated_at Timestamp user_id number
BeatmapsetDiscussionVote
Field Type Description beatmapset_discussion_id number created_at Timestamp id number score number updated_at Timestamp user_id number
Build
Field Type created_at Timestamp display_version string id number update_stream UpdateStream? users number version string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes changelog_entries ChangelogEntry[] If the build has no changelog entries, a placeholder is generated. versions Versions
Versions
ChangelogEntry
Field Type category string created_at Timestamp? github_pull_request_id number? github_url string? id number? major boolean repository string? title string? type string url string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes github_user GithubUser If the changelog entry has no GitHub user, a placeholder is generated. message string? Entry message in Markdown format. Embedded HTML is allowed. message_html string? Entry message in HTML format.
ChatChannel
Represents an individual chat «channel» in the game.
Channel Types
Type Permission Check for Joining/Messaging PUBLIC PRIVATE is player in the allowed groups? (channel.allowed_groups) MULTIPLAYER is player currently in the mp game? SPECTATOR TEMPORARY deprecated PM see below (user_channels) GROUP is player in channel? (user_channels)
For PMs, two factors are taken into account:
ChatMessage
Represents an individual Message within a ChatChannel.
Field Type Description message_id number unique identifier for message sender_id number user_id of the sender channel_id number channel_id of where the message was sent timestamp string when the message was sent, ISO-8601 content string message content is_action boolean was this an action? i.e. /me dances sender UserCompact embedded UserCompact object to save additional api lookups
Comment
Represents an single comment.
Field Type Description commentable_id number ID of the object the comment is attached to commentable_type string type of object the comment is attached to created_at string ISO 8601 date deleted_at string? ISO 8601 date if the comment was deleted; null, otherwise edited_at string? ISO 8601 date if the comment was edited; null, otherwise edited_by_id number? user id of the user that edited the post; null, otherwise id number the ID of the comment legacy_name string? username displayed on legacy comments message string? markdown of the comment’s content message_html string? html version of the comment’s content parent_id number? ID of the comment’s parent pinned boolean Pin status of the comment replies_count number number of replies to the comment updated_at string ISO 8601 date user_id number user ID of the poster votes_count number number of votes
CommentBundle
Comments and related data.
Field Type Description commentable_meta CommentableMeta[] ID of the object the comment is attached to comments Comment[] Array of comments ordered according to sort ; cursor Cursor has_more boolean If there are more comments or replies available has_more_id number? included_comments Comment[] Related comments; e.g. parent comments and nested replies pinned_comments Comment[]? Pinned comments sort string one of the CommentSort types top_level_count number? Number of comments at the top level. Not returned for replies. total number? Total number of comments. Not retuned for replies. user_follow boolean is the current user watching the comment thread? user_votes number[] IDs of the comments in the bundle the current user has upvoted users UserCompact[] array of users related to the comments
CommentSort
Type Sort Fields new created_at (descending), id (descending) old created_at (ascending), id (ascending) top votes_count (descending), created_at (descending), id (descending)
Building cursor for comments listing
The returned response will be for comments after the specified sort fields.
For example, use last loaded comment for the fields value to load more comments. Also make sure to use same sort and parent_id values.
CommentableMeta
Metadata of the object that a comment is attached to.
Field Type Description id number the ID of the object title string display title type string the type of the object url string url of the object
CurrentUserAttributes
An object listing various related permissions and states for the current user, related to the object it is attached to.
BeatmapsetDiscussionPermissions
TODO: needs a better name.
Name Description can_destroy Can delete the discussion. can_reopen Can reopen the discussion. can_moderate_kudosu Can allow or deny kudosu. can_resolve Can resolve the discussion. vote_score Current vote given to the discussion.
ChatChannelUserAttributes
Name Type Description can_message boolean Can send messages to this channel. can_message_error string? Reason messages cannot be sent to this channel last_read_id number message_id of last message read.
Cursor
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.
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
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-07-06
2022-06-08
2021-10-28
2021-09-01
2021-08-11
2021-06-14
2021-06-09
2021-04-20
2021-02-25
2020-09-08
2020-08-28
2020-05-01
2020-02-18
2019-10-09
2019-07-18
Endpoint
Base URL
The base URL is: https://osu.ppy.sh/api/[version]/
API Versions
This is combined with the base endpoint to determine where requests should be sent.
Version Status v2 current (not yet public, consider unstable and expect breaking changes) v1 legacy api provided by the old site, will be deprecated soon
Authentication
Routes marked with the OAuth label require a valid OAuth2 token for access.
More information about applications you have registered and granted permissions to can be found here.
The API supports the following grant types:
Before you can use the osu!api, you will need to
Registering an OAuth application
Before you can get an OAuth token, you will need to register an OAuth application on your account settings page
To register an OAuth application you will need to provide the:
Name Description Application Name This is the name that will be visible to users of your application. The name of your application cannot be changed. Application Callback URL The URL in your application where users will be sent after authorization.
The Application Callback URL is required when for using Authorization Codes. This may be left blank if you are only using Client Credentials Grants.
Your new OAuth application will have a Client ID and Client Secret ; the Client Secret is like a password for your OAuth application, it should be kept private and do not share it with anyone else.
Authorization Code Grant
The flow to authorize users for your application is:
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:
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:
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.
Make sure to replace <> 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:
Name Description chat.write Allows sending chat messages on a user’s behalf. delegate Allows acting as the owner of a client; only available for Client Credentials Grant. forum.write Allows creating and editing forum posts on a user’s behalf. friends.read Allows reading of the user’s friend list. identify Allows reading of the public profile of the user ( /me ). public Allows reading of publicly available data on behalf of the user.
identify is the default scope for the Authorization Code Grant and always implicitly provided. The Client Credentials Grant does not currently have any default scopes.
Routes marked with lazer are intended for use by the osu!lazer client and not currently available for use with Authorization Code or Client Credentials grants.
Using the chat.write scope requires either
Managing OAuth applications
Your account settings page will show your registered OAuth applications, and all the OAuth applications you have granted permissions to.
Reset Client Secret
You can generate a new Client Secret by choosing to «Reset client secret», however, this will disable all access tokens issued for the application.
Beatmaps
Lookup Beatmap
Response format
Get a User Beatmap score
Return a User’s score on a Beatmap
Response Format
The position returned depends on the requested mode and mods.
Get a User Beatmap scores
Return a User’s scores on a Beatmap
Response Format
Get Beatmap scores
Returns the top scores for a beatmap
Response Format
Get Beatmap scores (temp)
Returns the top scores for a beatmap from newer client.
This is a temporary endpoint.
Response Format
Get Beatmaps
Returns list of beatmaps.
Response format
Field Type Description beatmaps BeatmapCompact[] Includes: beatmapset (with ratings), failtimes, max_combo.
Get Beatmap
Gets beatmap data for the specified beatmap ID.
Response format
Returns Beatmap object. Following attributes are included in the response object when applicable,
Attribute Notes beatmapset Includes ratings property. failtimes max_combo
Get Beatmap Attributes
Returns difficulty attributes of beatmap with specific mode and mods combination.
Response format
Beatmapset Discussions
Get Beatmapset Discussion Posts
Returns the posts of beatmapset discussions.
Response Format
Get Beatmapset Discussion Votes
Returns the votes given to beatmapset discussions.
Response Format
Get Beatmapset Discussions
Returns a list of beatmapset discussions.
Response Format
Changelog
Get Changelog Build
Returns details of the specified build.
Response Format
Get Changelog Listing
Returns a listing of update streams, builds, and changelog entries.
Response Format
Lookup Changelog Build
Returns details of the specified build.
Response Format
Create New PM
This endpoint allows you to create a new PM channel.
Response Format
Field Type new_channel_id channel_id of newly created ChatChannel presence array of ChatChannel message the sent ChatMessage
This endpoint will only allow the creation of PMs initially, group chat support will come later.
Get Updates
This endpoint returns new messages since the given message_id along with updated channel ‘presence’ data.
Response Format
Get Channel Messages
This endpoint returns the chat messages for a specific channel.
Response Format
Returns an array of ChatMessage
Send Message to Channel
This endpoint returns the chat messages for a specific channel.
Response Format
Join Channel
This endpoint allows you to join a public or multiplayer channel.
Response Format
Returns the joined ChatChannel.
Leave Channel
This endpoint allows you to leave a public channel.
Response Format
Mark Channel as Read
Response Format
Get Channel List
This endpoint returns a list of all joinable public channels.
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.
Response Format
Returns ChatChannel with recent_messages attribute. Note that in the case of PM s, 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.
Response Format
Field Type Description channel ChatChannel users UserCompact Users are only visible for PM channels.
Comments
Get Comments
Returns a list comments and their replies up to 2 levels deep.
Response Format
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.
Response Format
Get a Comment
Gets a comment and its replies up to 2 levels deep.
Response Format
Edit Comment
Edit an existing comment.
Response Format
Delete Comment
Deletes the specified comment.
Response Format
Add Comment vote
Upvotes a comment.
Response Format
Remove Comment vote
Un-upvotes a comment.
Response Format
Forum
Reply Topic
Create a post replying to the specified topic.
Response Format
ForumPost with body included.
Create Topic
Create a new topic.
Response Format
Get Topic and Posts
Get topic and its posts.
Response Format
Edit Topic
Edit topic. Only title can be edited through this endpoint.
Response Format
Edit Post
Edit specified forum post.
Response Format
ForumPost with body included.
Search
Searches users and wiki pages.
Response Format
SearchResult
Multiplayer
Get User High Score
Returns detail of highest score of specified user and the surrounding scores.
Response Format
Get Scores
Returns a list of scores for specified playlist item.
Response Format
Get a Score
Returns detail of specified score and the surrounding scores.
Response Format
Get News Listing
Returns a list of news posts and related metadata.
Response Format
Get News Post
Returns details of the specified news post.
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.
Response Format
Returns an object containing Notification and other related attributes.
Field Type has_more boolean whether or not there are more notifications notifications array of Notification unread_count total unread notifications notification_endpoint url to connect to websocket server
Mark Notifications as Read
This endpoint allows you to mark notifications read.
Response Format
OAuth Tokens
Revoke current token
Revokes currently authenticated token.
Ranking
Get Ranking
Gets the current ranking for the specified type and game mode.
Response Format
Get Spotlights
Gets the list of spotlights.
Response Format
Undocumented
/beatmaps//solo/scores
/beatmaps//solo/scores//beatmapsets/events
/beatmapsets//favourites
/chat/presence
/matches
/matches//rooms//rooms//users//rooms//users//rooms//leaderboard
/rooms//playlist//scores
/rooms//playlist//scores//reports
/rooms
/rooms//seasonal-backgrounds
/scores///download
/scores///beatmapsets/search//beatmapsets/lookup
/beatmapsets//friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
Similar to Get User but with authenticated user (token owner) as user id.
Response format
Additionally, statistics_rulesets is included, containing statistics for all rulesets.
Get User Kudosu
Returns kudosu history.
Response format
Get User Scores
This endpoint returns the scores of specified user.
Response format
Array of Score. Following attributes are included in the response object when applicable.
Get User Beatmaps
Returns the beatmaps of specified user.
Type Notes favourite graveyard loved most_played pending Previously unranked ranked Previously ranked_and_approved
Response format
Array of BeatmapPlaycount when type is most_played ; array of Beatmapset, otherwise.
Get User Recent Activity
Returns recent activity.
Response format
Get User
This endpoint returns the detail of specified user.
Response format
Returns User object. The following optional attributes on UserCompact are included:
Get Users
Returns list of users.
Response format
Field Type Description users UserCompact[] Includes: country, cover, groups, statistics_rulesets.
Get Wiki Page
The wiki article or image data.
Response Format
Notification Websocket
Connection
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:
Field Type Description event string See below
logout event
Server will disconnect session after sending this event so don’t try to reconnect.
Field Type Description event string logout
new event
New notification. See Notification object for notification types.
Field Type Description event string new data Notification
read event
Notification has been read.
Field Type Description event string read ids number[] id of Notifications which are read
Object Structures
Beatmap
Represent a beatmap. This extends BeatmapCompact with additional attributes.
Field Type Description accuracy float ar float beatmapset_id integer bpm float? convert boolean count_circles integer count_sliders integer count_spinners integer cs float deleted_at Timestamp? drain float hit_length integer is_scoreable boolean last_updated Timestamp mode_int integer passcount integer playcount integer ranked integer See Rank status for list of possible values. url string
BeatmapCompact
Represent a beatmap.
Field Type Description beatmapset_id integer difficulty_rating float id integer mode GameMode status string See Rank status for list of possible values. total_length integer user_id integer version string
Field Type Description beatmapset Beatmapset|BeatmapsetCompact|null Beatmapset for Beatmap object, BeatmapsetCompact for BeatmapCompact object. null if the beatmap doesn’t have associated beatmapset (e.g. deleted). checksum string? failtimes Failtimes max_combo integer
Failtimes
All fields are optional but there’s always at least one field returned.
Field Type Description exit integer[]? Array of length 100. fail integer[]? Array of length 100.
BeatmapDifficultyAttributes
Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.
Field Type max_combo integer star_rating float
Field Type aim_difficulty float approach_rate float flashlight_difficulty float overall_difficulty float slider_factor float speed_difficulty float
taiko
Field Type stamina_difficulty float rhythm_difficulty float colour_difficulty float approach_rate float great_hit_window float
fruits
mania
Field Type great_hit_window float score_multiplier float
BeatmapPlaycount
Represent the playcount of a beatmap.
Field Type Description beatmap_id number beatmap BeatmapCompact? beatmapset BeatmapsetCompact? count number
BeatmapScores
Field Type Description scores Score[] The list of top scores for the beatmap in descending order. userScore BeatmapUserScore? The score of the current user. This is not returned if the current user does not have a score. Note: will be moved to user_score in the future
BeatmapUserScore
Field Type Description position number The position of the score within the requested beatmap ranking. score Score The details of the score.
Beatmapset
Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.
Field Type Description availability.download_disabled boolean availability.more_information string? bpm float can_be_hyped boolean creator string Username of the mapper at the time of beatmapset creation. discussion_locked boolean hype.current integer hype.required integer is_scoreable boolean last_updated Timestamp legacy_thread_url string? nominations.current integer nominations.required integer ranked integer See Rank status for list of possible values. ranked_date Timestamp? source string storyboard boolean submitted_date Timestamp? tags string
The following attributes are always included as well:
Field has_favourited
BeatmapsetCompact
Represents a beatmapset.
Field Type Description artist string artist_unicode string covers Covers creator string favourite_count number id number nsfw boolean play_count number preview_url string source string status string title string title_unicode string user_id number video boolean
Those fields are optional.
Field Type Description beatmaps Beatmap[] converts current_user_attributes description discussions events genre has_favourited boolean language nominations ratings recent_favourites related_users user
Covers
Field Type cover string cover@2x string card string card@2x string list string list@2x string slimcover string slimcover@2x string
Rank status
The possible values are denoted either as integer or string.
Integer String -2 graveyard -1 wip 0 pending 1 ranked 2 approved 3 qualified 4 loved
BeatmapsetDiscussion
Represents a Beatmapset modding discussion.
Field Type Description beatmap BeatmapCompact? beatmap_id number? beatmapset BeatmapsetCompact? beatmapset_id number can_be_resolved boolean can_grant_kudosu boolean created_at Timestamp current_user_attributes CurrentUserAttributes deleted_at Timestamp? deleted_by_id number? id number kudosu_denied boolean last_post_at Timestamp message_type MessageType parent_id number? posts BeatmapsetDiscussionPost[]? resolved boolean starting_post BeatmapsetDiscussionPost? timestamp number? updated_at Timestamp user_id number
MessageType
Name Description hype mapper_note praise problem review suggestion
BeatmapsetDiscussionPost
Field Type Description beatmapset_discussion_id number created_at Timestamp deleted_at Timestamp? deleted_by_id number? id number last_editor_id number? message string system boolean updated_at Timestamp user_id number
BeatmapsetDiscussionVote
Field Type Description beatmapset_discussion_id number created_at Timestamp id number score number updated_at Timestamp user_id number
Build
Field Type created_at Timestamp display_version string id number update_stream UpdateStream? users number version string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes changelog_entries ChangelogEntry[] If the build has no changelog entries, a placeholder is generated. versions Versions
Versions
ChangelogEntry
Field Type category string created_at Timestamp? github_pull_request_id number? github_url string? id number? major boolean repository string? title string? type string url string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes github_user GithubUser If the changelog entry has no GitHub user, a placeholder is generated. message string? Entry message in Markdown format. Embedded HTML is allowed. message_html string? Entry message in HTML format.
ChatChannel
Represents an individual chat «channel» in the game.
Channel Types
Type Permission Check for Joining/Messaging PUBLIC PRIVATE is player in the allowed groups? (channel.allowed_groups) MULTIPLAYER is player currently in the mp game? SPECTATOR TEMPORARY deprecated PM see below (user_channels) GROUP is player in channel? (user_channels)
For PMs, two factors are taken into account:
ChatMessage
Represents an individual Message within a ChatChannel.
Field Type Description message_id number unique identifier for message sender_id number user_id of the sender channel_id number channel_id of where the message was sent timestamp string when the message was sent, ISO-8601 content string message content is_action boolean was this an action? i.e. /me dances sender UserCompact embedded UserCompact object to save additional api lookups
Comment
Represents an single comment.
Field Type Description commentable_id number ID of the object the comment is attached to commentable_type string type of object the comment is attached to created_at string ISO 8601 date deleted_at string? ISO 8601 date if the comment was deleted; null, otherwise edited_at string? ISO 8601 date if the comment was edited; null, otherwise edited_by_id number? user id of the user that edited the post; null, otherwise id number the ID of the comment legacy_name string? username displayed on legacy comments message string? markdown of the comment’s content message_html string? html version of the comment’s content parent_id number? ID of the comment’s parent pinned boolean Pin status of the comment replies_count number number of replies to the comment updated_at string ISO 8601 date user_id number user ID of the poster votes_count number number of votes
CommentBundle
Comments and related data.
Field Type Description commentable_meta CommentableMeta[] ID of the object the comment is attached to comments Comment[] Array of comments ordered according to sort ; cursor Cursor has_more boolean If there are more comments or replies available has_more_id number? included_comments Comment[] Related comments; e.g. parent comments and nested replies pinned_comments Comment[]? Pinned comments sort string one of the CommentSort types top_level_count number? Number of comments at the top level. Not returned for replies. total number? Total number of comments. Not retuned for replies. user_follow boolean is the current user watching the comment thread? user_votes number[] IDs of the comments in the bundle the current user has upvoted users UserCompact[] array of users related to the comments
CommentSort
Type Sort Fields new created_at (descending), id (descending) old created_at (ascending), id (ascending) top votes_count (descending), created_at (descending), id (descending)
Building cursor for comments listing
The returned response will be for comments after the specified sort fields.
For example, use last loaded comment for the fields value to load more comments. Also make sure to use same sort and parent_id values.
CommentableMeta
Metadata of the object that a comment is attached to.
Field Type Description id number the ID of the object title string display title type string the type of the object url string url of the object
CurrentUserAttributes
An object listing various related permissions and states for the current user, related to the object it is attached to.
BeatmapsetDiscussionPermissions
TODO: needs a better name.
Name Description can_destroy Can delete the discussion. can_reopen Can reopen the discussion. can_moderate_kudosu Can allow or deny kudosu. can_resolve Can resolve the discussion. vote_score Current vote given to the discussion.
ChatChannelUserAttributes
Name Type Description can_message boolean Can send messages to this channel. can_message_error string? Reason messages cannot be sent to this channel last_read_id number message_id of last message read.
Cursor
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.
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
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-07-06
2022-06-08
2021-10-28
2021-09-01
2021-08-11
2021-06-14
2021-06-09
2021-04-20
2021-02-25
2020-09-08
2020-08-28
2020-05-01
2020-02-18
2019-10-09
2019-07-18
Endpoint
Base URL
The base URL is: https://osu.ppy.sh/api/[version]/
API Versions
This is combined with the base endpoint to determine where requests should be sent.
Version Status v2 current (not yet public, consider unstable and expect breaking changes) v1 legacy api provided by the old site, will be deprecated soon
Authentication
Routes marked with the OAuth label require a valid OAuth2 token for access.
More information about applications you have registered and granted permissions to can be found here.
The API supports the following grant types:
Before you can use the osu!api, you will need to
Registering an OAuth application
Before you can get an OAuth token, you will need to register an OAuth application on your account settings page
To register an OAuth application you will need to provide the:
Name Description Application Name This is the name that will be visible to users of your application. The name of your application cannot be changed. Application Callback URL The URL in your application where users will be sent after authorization.
The Application Callback URL is required when for using Authorization Codes. This may be left blank if you are only using Client Credentials Grants.
Your new OAuth application will have a Client ID and Client Secret ; the Client Secret is like a password for your OAuth application, it should be kept private and do not share it with anyone else.
Authorization Code Grant
The flow to authorize users for your application is:
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:
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:
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.
Make sure to replace <> 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:
Name Description chat.write Allows sending chat messages on a user’s behalf. delegate Allows acting as the owner of a client; only available for Client Credentials Grant. forum.write Allows creating and editing forum posts on a user’s behalf. friends.read Allows reading of the user’s friend list. identify Allows reading of the public profile of the user ( /me ). public Allows reading of publicly available data on behalf of the user.
identify is the default scope for the Authorization Code Grant and always implicitly provided. The Client Credentials Grant does not currently have any default scopes.
Routes marked with lazer are intended for use by the osu!lazer client and not currently available for use with Authorization Code or Client Credentials grants.
Using the chat.write scope requires either
Managing OAuth applications
Your account settings page will show your registered OAuth applications, and all the OAuth applications you have granted permissions to.
Reset Client Secret
You can generate a new Client Secret by choosing to «Reset client secret», however, this will disable all access tokens issued for the application.
Beatmaps
Lookup Beatmap
Response format
Get a User Beatmap score
Return a User’s score on a Beatmap
Response Format
The position returned depends on the requested mode and mods.
Get a User Beatmap scores
Return a User’s scores on a Beatmap
Response Format
Get Beatmap scores
Returns the top scores for a beatmap
Response Format
Get Beatmap scores (temp)
Returns the top scores for a beatmap from newer client.
This is a temporary endpoint.
Response Format
Get Beatmaps
Returns list of beatmaps.
Response format
Field Type Description beatmaps BeatmapCompact[] Includes: beatmapset (with ratings), failtimes, max_combo.
Get Beatmap
Gets beatmap data for the specified beatmap ID.
Response format
Returns Beatmap object. Following attributes are included in the response object when applicable,
Attribute Notes beatmapset Includes ratings property. failtimes max_combo
Get Beatmap Attributes
Returns difficulty attributes of beatmap with specific mode and mods combination.
Response format
Beatmapset Discussions
Get Beatmapset Discussion Posts
Returns the posts of beatmapset discussions.
Response Format
Get Beatmapset Discussion Votes
Returns the votes given to beatmapset discussions.
Response Format
Get Beatmapset Discussions
Returns a list of beatmapset discussions.
Response Format
Changelog
Get Changelog Build
Returns details of the specified build.
Response Format
Get Changelog Listing
Returns a listing of update streams, builds, and changelog entries.
Response Format
Lookup Changelog Build
Returns details of the specified build.
Response Format
Create New PM
This endpoint allows you to create a new PM channel.
Response Format
Field Type new_channel_id channel_id of newly created ChatChannel presence array of ChatChannel message the sent ChatMessage
This endpoint will only allow the creation of PMs initially, group chat support will come later.
Get Updates
This endpoint returns new messages since the given message_id along with updated channel ‘presence’ data.
Response Format
Get Channel Messages
This endpoint returns the chat messages for a specific channel.
Response Format
Returns an array of ChatMessage
Send Message to Channel
This endpoint returns the chat messages for a specific channel.
Response Format
Join Channel
This endpoint allows you to join a public or multiplayer channel.
Response Format
Returns the joined ChatChannel.
Leave Channel
This endpoint allows you to leave a public channel.
Response Format
Mark Channel as Read
Response Format
Get Channel List
This endpoint returns a list of all joinable public channels.
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.
Response Format
Returns ChatChannel with recent_messages attribute. Note that in the case of PM s, 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.
Response Format
Field Type Description channel ChatChannel users UserCompact Users are only visible for PM channels.
Comments
Get Comments
Returns a list comments and their replies up to 2 levels deep.
Response Format
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.
Response Format
Get a Comment
Gets a comment and its replies up to 2 levels deep.
Response Format
Edit Comment
Edit an existing comment.
Response Format
Delete Comment
Deletes the specified comment.
Response Format
Add Comment vote
Upvotes a comment.
Response Format
Remove Comment vote
Un-upvotes a comment.
Response Format
Forum
Reply Topic
Create a post replying to the specified topic.
Response Format
ForumPost with body included.
Create Topic
Create a new topic.
Response Format
Get Topic and Posts
Get topic and its posts.
Response Format
Edit Topic
Edit topic. Only title can be edited through this endpoint.
Response Format
Edit Post
Edit specified forum post.
Response Format
ForumPost with body included.
Search
Searches users and wiki pages.
Response Format
SearchResult
Multiplayer
Get User High Score
Returns detail of highest score of specified user and the surrounding scores.
Response Format
Get Scores
Returns a list of scores for specified playlist item.
Response Format
Get a Score
Returns detail of specified score and the surrounding scores.
Response Format
Get News Listing
Returns a list of news posts and related metadata.
Response Format
Get News Post
Returns details of the specified news post.
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.
Response Format
Returns an object containing Notification and other related attributes.
Field Type has_more boolean whether or not there are more notifications notifications array of Notification unread_count total unread notifications notification_endpoint url to connect to websocket server
Mark Notifications as Read
This endpoint allows you to mark notifications read.
Response Format
OAuth Tokens
Revoke current token
Revokes currently authenticated token.
Ranking
Get Ranking
Gets the current ranking for the specified type and game mode.
Response Format
Get Spotlights
Gets the list of spotlights.
Response Format
Undocumented
/beatmaps//solo/scores
/beatmaps//solo/scores//beatmapsets/events
/beatmapsets//favourites
/chat/presence
/matches
/matches//rooms//rooms//users//rooms//users//rooms//leaderboard
/rooms//playlist//scores
/rooms//playlist//scores//reports
/rooms
/rooms//seasonal-backgrounds
/scores///download
/scores///beatmapsets/search//beatmapsets/lookup
/beatmapsets//friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
Similar to Get User but with authenticated user (token owner) as user id.
Response format
Additionally, statistics_rulesets is included, containing statistics for all rulesets.
Get User Kudosu
Returns kudosu history.
Response format
Get User Scores
This endpoint returns the scores of specified user.
Response format
Array of Score. Following attributes are included in the response object when applicable.
Get User Beatmaps
Returns the beatmaps of specified user.
Type Notes favourite graveyard loved most_played pending Previously unranked ranked Previously ranked_and_approved
Response format
Array of BeatmapPlaycount when type is most_played ; array of Beatmapset, otherwise.
Get User Recent Activity
Returns recent activity.
Response format
Get User
This endpoint returns the detail of specified user.
Response format
Returns User object. The following optional attributes on UserCompact are included:
Get Users
Returns list of users.
Response format
Field Type Description users UserCompact[] Includes: country, cover, groups, statistics_rulesets.
Get Wiki Page
The wiki article or image data.
Response Format
Notification Websocket
Connection
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:
Field Type Description event string See below
logout event
Server will disconnect session after sending this event so don’t try to reconnect.
Field Type Description event string logout
new event
New notification. See Notification object for notification types.
Field Type Description event string new data Notification
read event
Notification has been read.
Field Type Description event string read ids number[] id of Notifications which are read
Object Structures
Beatmap
Represent a beatmap. This extends BeatmapCompact with additional attributes.
Field Type Description accuracy float ar float beatmapset_id integer bpm float? convert boolean count_circles integer count_sliders integer count_spinners integer cs float deleted_at Timestamp? drain float hit_length integer is_scoreable boolean last_updated Timestamp mode_int integer passcount integer playcount integer ranked integer See Rank status for list of possible values. url string
BeatmapCompact
Represent a beatmap.
Field Type Description beatmapset_id integer difficulty_rating float id integer mode GameMode status string See Rank status for list of possible values. total_length integer user_id integer version string
Field Type Description beatmapset Beatmapset|BeatmapsetCompact|null Beatmapset for Beatmap object, BeatmapsetCompact for BeatmapCompact object. null if the beatmap doesn’t have associated beatmapset (e.g. deleted). checksum string? failtimes Failtimes max_combo integer
Failtimes
All fields are optional but there’s always at least one field returned.
Field Type Description exit integer[]? Array of length 100. fail integer[]? Array of length 100.
BeatmapDifficultyAttributes
Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.
Field Type max_combo integer star_rating float
Field Type aim_difficulty float approach_rate float flashlight_difficulty float overall_difficulty float slider_factor float speed_difficulty float
taiko
Field Type stamina_difficulty float rhythm_difficulty float colour_difficulty float approach_rate float great_hit_window float
fruits
mania
Field Type great_hit_window float score_multiplier float
BeatmapPlaycount
Represent the playcount of a beatmap.
Field Type Description beatmap_id number beatmap BeatmapCompact? beatmapset BeatmapsetCompact? count number
BeatmapScores
Field Type Description scores Score[] The list of top scores for the beatmap in descending order. userScore BeatmapUserScore? The score of the current user. This is not returned if the current user does not have a score. Note: will be moved to user_score in the future
BeatmapUserScore
Field Type Description position number The position of the score within the requested beatmap ranking. score Score The details of the score.
Beatmapset
Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.
Field Type Description availability.download_disabled boolean availability.more_information string? bpm float can_be_hyped boolean creator string Username of the mapper at the time of beatmapset creation. discussion_locked boolean hype.current integer hype.required integer is_scoreable boolean last_updated Timestamp legacy_thread_url string? nominations.current integer nominations.required integer ranked integer See Rank status for list of possible values. ranked_date Timestamp? source string storyboard boolean submitted_date Timestamp? tags string
The following attributes are always included as well:
Field has_favourited
BeatmapsetCompact
Represents a beatmapset.
Field Type Description artist string artist_unicode string covers Covers creator string favourite_count number id number nsfw boolean play_count number preview_url string source string status string title string title_unicode string user_id number video boolean
Those fields are optional.
Field Type Description beatmaps Beatmap[] converts current_user_attributes description discussions events genre has_favourited boolean language nominations ratings recent_favourites related_users user
Covers
Field Type cover string cover@2x string card string card@2x string list string list@2x string slimcover string slimcover@2x string
Rank status
The possible values are denoted either as integer or string.
Integer String -2 graveyard -1 wip 0 pending 1 ranked 2 approved 3 qualified 4 loved
BeatmapsetDiscussion
Represents a Beatmapset modding discussion.
Field Type Description beatmap BeatmapCompact? beatmap_id number? beatmapset BeatmapsetCompact? beatmapset_id number can_be_resolved boolean can_grant_kudosu boolean created_at Timestamp current_user_attributes CurrentUserAttributes deleted_at Timestamp? deleted_by_id number? id number kudosu_denied boolean last_post_at Timestamp message_type MessageType parent_id number? posts BeatmapsetDiscussionPost[]? resolved boolean starting_post BeatmapsetDiscussionPost? timestamp number? updated_at Timestamp user_id number
MessageType
Name Description hype mapper_note praise problem review suggestion
BeatmapsetDiscussionPost
Field Type Description beatmapset_discussion_id number created_at Timestamp deleted_at Timestamp? deleted_by_id number? id number last_editor_id number? message string system boolean updated_at Timestamp user_id number
BeatmapsetDiscussionVote
Field Type Description beatmapset_discussion_id number created_at Timestamp id number score number updated_at Timestamp user_id number
Build
Field Type created_at Timestamp display_version string id number update_stream UpdateStream? users number version string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes changelog_entries ChangelogEntry[] If the build has no changelog entries, a placeholder is generated. versions Versions
Versions
ChangelogEntry
Field Type category string created_at Timestamp? github_pull_request_id number? github_url string? id number? major boolean repository string? title string? type string url string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes github_user GithubUser If the changelog entry has no GitHub user, a placeholder is generated. message string? Entry message in Markdown format. Embedded HTML is allowed. message_html string? Entry message in HTML format.
ChatChannel
Represents an individual chat «channel» in the game.
Channel Types
Type Permission Check for Joining/Messaging PUBLIC PRIVATE is player in the allowed groups? (channel.allowed_groups) MULTIPLAYER is player currently in the mp game? SPECTATOR TEMPORARY deprecated PM see below (user_channels) GROUP is player in channel? (user_channels)
For PMs, two factors are taken into account:
ChatMessage
Represents an individual Message within a ChatChannel.
Field Type Description message_id number unique identifier for message sender_id number user_id of the sender channel_id number channel_id of where the message was sent timestamp string when the message was sent, ISO-8601 content string message content is_action boolean was this an action? i.e. /me dances sender UserCompact embedded UserCompact object to save additional api lookups
Comment
Represents an single comment.
Field Type Description commentable_id number ID of the object the comment is attached to commentable_type string type of object the comment is attached to created_at string ISO 8601 date deleted_at string? ISO 8601 date if the comment was deleted; null, otherwise edited_at string? ISO 8601 date if the comment was edited; null, otherwise edited_by_id number? user id of the user that edited the post; null, otherwise id number the ID of the comment legacy_name string? username displayed on legacy comments message string? markdown of the comment’s content message_html string? html version of the comment’s content parent_id number? ID of the comment’s parent pinned boolean Pin status of the comment replies_count number number of replies to the comment updated_at string ISO 8601 date user_id number user ID of the poster votes_count number number of votes
CommentBundle
Comments and related data.
Field Type Description commentable_meta CommentableMeta[] ID of the object the comment is attached to comments Comment[] Array of comments ordered according to sort ; cursor Cursor has_more boolean If there are more comments or replies available has_more_id number? included_comments Comment[] Related comments; e.g. parent comments and nested replies pinned_comments Comment[]? Pinned comments sort string one of the CommentSort types top_level_count number? Number of comments at the top level. Not returned for replies. total number? Total number of comments. Not retuned for replies. user_follow boolean is the current user watching the comment thread? user_votes number[] IDs of the comments in the bundle the current user has upvoted users UserCompact[] array of users related to the comments
CommentSort
Type Sort Fields new created_at (descending), id (descending) old created_at (ascending), id (ascending) top votes_count (descending), created_at (descending), id (descending)
Building cursor for comments listing
The returned response will be for comments after the specified sort fields.
For example, use last loaded comment for the fields value to load more comments. Also make sure to use same sort and parent_id values.
CommentableMeta
Metadata of the object that a comment is attached to.
Field Type Description id number the ID of the object title string display title type string the type of the object url string url of the object
CurrentUserAttributes
An object listing various related permissions and states for the current user, related to the object it is attached to.
BeatmapsetDiscussionPermissions
TODO: needs a better name.
Name Description can_destroy Can delete the discussion. can_reopen Can reopen the discussion. can_moderate_kudosu Can allow or deny kudosu. can_resolve Can resolve the discussion. vote_score Current vote given to the discussion.
ChatChannelUserAttributes
Name Type Description can_message boolean Can send messages to this channel. can_message_error string? Reason messages cannot be sent to this channel last_read_id number message_id of last message read.
Cursor
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.
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
osu!api open beta
Нет аккаунта?
osu!api open beta
I’ve had an API available for a while but until now it has been on a private on-request basis. In order to try and make developing third party services which expand and support osu!, I have added an API key setup and started to document the API.
Documentation will be expanded as I find time to do so! If anyone currently using the API is able to help expand the documentation then please do.
comentarinformal wrote:
Before I spam it with requests that might not exist, is there anything to get user’s information?
(Also, is there anything to login users from this page in other places?)
There is /api/get_user
Gonna write an entry with the information I have about it.
Is there a fair use limit? (e.g. no more than XX requests per day)
For get_user, I suppose there is a mode parameter for getting user information for Taiko, CtB and osu!mania? Or do I have to file an issue in GitHub? Nevermind, I found it, the parameter to add is called «m» I have edited the GitHub wiki.
Oh well. I have some questions:
Are only the beatmap and user endpoints available?
The parameter «since» in /get_beatmap how I need to pass the time on it? UTC or unix timestamp?
Do I need to pass the key on the wiki’s API too?
Edit: What the countX values mean? Number of beatmaps?
comentarinformal wrote:
Before I spam it with requests that might not exist, is there anything to get user’s information?
(Also, is there anything to login users from this page in other places?)
I guess I’ll update my userbar too when I find some time.
Damnae wrote:
I guess I’ll update my userbar too when I find some time.
I registered it for osu!userbar, but I also use it for my «Big ugly white signature», they are not on the same webserver, but it works fine
I belive only you and peppy can see the name you used, too.
(Yes I took my lazyness off, it was not that long to update ^^)
@Repflez: I tried using your API-powered signature and I get something weird.
Since I only aim for SS, I have 100% Accuracy all the time, and the Accuracy display is weird.
(I now know that despite having all-SS records, the note hit count for getting 50s and 100s are still counted all the time )
Winshley wrote:
@Repflez: I tried using your API-powered signature and I get something weird.
Since I only aim for SS, I have 100% Accuracy all the time, and the Accuracy display is weird.
(I now know that despite having all-SS records, the note hit count for getting 50s and 100s are still counted all the time )
So that’s what the CountX values mean. Thanks for that. I already went and changed the accuracy to show a centered «100% Accuracy» if it’s 100. Forget that. I ditched the bar on it and used the extra space for showing the PP.
(I love how the 300 count ended overlaping the border)
Repflez wrote:
So that’s what the CountX values mean. Thanks for that.
Yeah. At first I thought that there was something wrong with the API showing 50s and 100s despite having 100% Accuracy, until I actually calculated all 300s + 100s + 50s = «Total Hits» on our profile.
About the 300 overlap though, it does need some fix:
When you reached 10 millions of 300 hits, the last number is cut off. Cookiezi has 17 millions of 300 hits.
I’m not sure how the level bar breaking happens though. I was thinking that it probably because I don’t have any ranked score on osu!mania?
[Archived] getting osu! api token
Нет аккаунта?
[Archived] getting osu! api token
here is the website I am currently using this for https://osu-api-crap.minecreeper0913.repl.co
well since the project I am using is all python and not javascript I am using a new tab browser to just test it and so far the code I am using is
url = («https://osu.ppy.sh/oauth/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=%s» % (code))
the &code=%s is basically just grabbing the code that has been given back by oauth and using that as the url, when I am testing it though I am actually using my code
Never share your client secret, it’s secret for a reason. I would recommend resetting it ASAP.
Are you just typing that URL into your browser or are you actually sending it as a post request with whatever python code you have? Typing the URL into your browser won’t work.
The token endpoint takes the parameters in the body of the request, not as query parameters. You are also missing some parameters, like redirect_uri and grant_type.
If you are using python’s requests library, you can do something like this:
Might have some syntax errors because I wrote that from memory and didn’t check anything in an IDE or by running it.
You can try without specifying the content type in your headers, it might work without it. Very simply, the content type header describes what type of content or data is being sent. As far as I recall, the server is expecting that content type but I could be wrong.
now starting to realize that I might have done this a bit wrong, this is the first time I have used an API for something so everything I am doing is new to me.
So the first thing that is happening is that you press the login to link your osu API to the website, then it grabs your code and redirects you to the home website with the code in the url for example http://www.website.com/code=j9838r9y82g9438gh8243hg384hg, and it is supposed to use that, but when in testing it just returns favicon.ico, and I don’t know what that is or means so I might have to change my get request, another issue is but how would I make it get that auth code?
I don’t know anything about the project you are working on, so unfortunately I don’t think I can really answer any of the questions you’re asking.
I don’t know what you mean by a favicon being returned and I also don’t know what you are using the handle the backend of your site, so I can’t specifically tell you how to grab the code. Whatever you are using should have some way of getting query parameters from the URL.
Oauth2 is a very standardized and should be nearly the same everywhere that uses it. osu! is no exception. I would highly recommend looking up and reading about the authorization code flow that you are trying to use here. There should be a ton of resources and maybe a few code examples as well.
There might not be any videos specific to osu!’s API, but there are definitely Oauth2 tutorial videos and examples out there in probably every programming language, which is what you are dealing with right now.
For example, here is a video I found after a quick Google search that is using Python. I can’t fully comment on its quality since I just skimmed through it, but the general flow that the creator of the video goes over seems like it will at least cover how OAuth2 works in general, even if it’s not in the context of osu!’s API.
And even if you don’t really like reading, there are still some pretty good resources you can use that might help in addition to watching a video. Like this and this for example. Again, I’ve only skimmed through these, but they also seem to be pretty good.
here is the code I use:
NOTE I did not actually use SECRET as the secret I have it as SECRET because its secret
/rooms//leaderboard
/rooms//playlist//scores
/rooms//playlist//scores//reports
/rooms
/rooms//seasonal-backgrounds
/scores///download
/scores///beatmapsets/search//beatmapsets/lookup
/beatmapsets//friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
Similar to Get User but with authenticated user (token owner) as user id.
Response format
Additionally, statistics_rulesets is included, containing statistics for all rulesets.
Get User Kudosu
Returns kudosu history.
Response format
Get User Scores
This endpoint returns the scores of specified user.
Response format
Array of Score. Following attributes are included in the response object when applicable.
Get User Beatmaps
Returns the beatmaps of specified user.
Type Notes favourite graveyard loved most_played pending Previously unranked ranked Previously ranked_and_approved
Response format
Array of BeatmapPlaycount when type is most_played ; array of Beatmapset, otherwise.
Get User Recent Activity
Returns recent activity.
Response format
Get User
This endpoint returns the detail of specified user.
Response format
Returns User object. The following optional attributes on UserCompact are included:
Get Users
Returns list of users.
Response format
Field Type Description users UserCompact[] Includes: country, cover, groups, statistics_rulesets.
Get Wiki Page
The wiki article or image data.
Response Format
Notification Websocket
Connection
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:
Field Type Description event string See below
logout event
Server will disconnect session after sending this event so don’t try to reconnect.
Field Type Description event string logout
new event
New notification. See Notification object for notification types.
Field Type Description event string new data Notification
read event
Notification has been read.
Field Type Description event string read ids number[] id of Notifications which are read
Object Structures
Beatmap
Represent a beatmap. This extends BeatmapCompact with additional attributes.
Field Type Description accuracy float ar float beatmapset_id integer bpm float? convert boolean count_circles integer count_sliders integer count_spinners integer cs float deleted_at Timestamp? drain float hit_length integer is_scoreable boolean last_updated Timestamp mode_int integer passcount integer playcount integer ranked integer See Rank status for list of possible values. url string
BeatmapCompact
Represent a beatmap.
Field Type Description beatmapset_id integer difficulty_rating float id integer mode GameMode status string See Rank status for list of possible values. total_length integer user_id integer version string
Field Type Description beatmapset Beatmapset|BeatmapsetCompact|null Beatmapset for Beatmap object, BeatmapsetCompact for BeatmapCompact object. null if the beatmap doesn’t have associated beatmapset (e.g. deleted). checksum string? failtimes Failtimes max_combo integer
Failtimes
All fields are optional but there’s always at least one field returned.
Field Type Description exit integer[]? Array of length 100. fail integer[]? Array of length 100.
BeatmapDifficultyAttributes
Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.
Field Type max_combo integer star_rating float
Field Type aim_difficulty float approach_rate float flashlight_difficulty float overall_difficulty float slider_factor float speed_difficulty float
taiko
Field Type stamina_difficulty float rhythm_difficulty float colour_difficulty float approach_rate float great_hit_window float
fruits
mania
Field Type great_hit_window float score_multiplier float
BeatmapPlaycount
Represent the playcount of a beatmap.
Field Type Description beatmap_id number beatmap BeatmapCompact? beatmapset BeatmapsetCompact? count number
BeatmapScores
Field Type Description scores Score[] The list of top scores for the beatmap in descending order. userScore BeatmapUserScore? The score of the current user. This is not returned if the current user does not have a score. Note: will be moved to user_score in the future
BeatmapUserScore
Field Type Description position number The position of the score within the requested beatmap ranking. score Score The details of the score.
Beatmapset
Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.
Field Type Description availability.download_disabled boolean availability.more_information string? bpm float can_be_hyped boolean creator string Username of the mapper at the time of beatmapset creation. discussion_locked boolean hype.current integer hype.required integer is_scoreable boolean last_updated Timestamp legacy_thread_url string? nominations.current integer nominations.required integer ranked integer See Rank status for list of possible values. ranked_date Timestamp? source string storyboard boolean submitted_date Timestamp? tags string
The following attributes are always included as well:
Field has_favourited
BeatmapsetCompact
Represents a beatmapset.
Field Type Description artist string artist_unicode string covers Covers creator string favourite_count number id number nsfw boolean play_count number preview_url string source string status string title string title_unicode string user_id number video boolean
Those fields are optional.
Field Type Description beatmaps Beatmap[] converts current_user_attributes description discussions events genre has_favourited boolean language nominations ratings recent_favourites related_users user
Covers
Field Type cover string cover@2x string card string card@2x string list string list@2x string slimcover string slimcover@2x string
Rank status
The possible values are denoted either as integer or string.
Integer String -2 graveyard -1 wip 0 pending 1 ranked 2 approved 3 qualified 4 loved
BeatmapsetDiscussion
Represents a Beatmapset modding discussion.
Field Type Description beatmap BeatmapCompact? beatmap_id number? beatmapset BeatmapsetCompact? beatmapset_id number can_be_resolved boolean can_grant_kudosu boolean created_at Timestamp current_user_attributes CurrentUserAttributes deleted_at Timestamp? deleted_by_id number? id number kudosu_denied boolean last_post_at Timestamp message_type MessageType parent_id number? posts BeatmapsetDiscussionPost[]? resolved boolean starting_post BeatmapsetDiscussionPost? timestamp number? updated_at Timestamp user_id number
MessageType
Name Description hype mapper_note praise problem review suggestion
BeatmapsetDiscussionPost
Field Type Description beatmapset_discussion_id number created_at Timestamp deleted_at Timestamp? deleted_by_id number? id number last_editor_id number? message string system boolean updated_at Timestamp user_id number
BeatmapsetDiscussionVote
Field Type Description beatmapset_discussion_id number created_at Timestamp id number score number updated_at Timestamp user_id number
Build
Field Type created_at Timestamp display_version string id number update_stream UpdateStream? users number version string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes changelog_entries ChangelogEntry[] If the build has no changelog entries, a placeholder is generated. versions Versions
Versions
ChangelogEntry
Field Type category string created_at Timestamp? github_pull_request_id number? github_url string? id number? major boolean repository string? title string? type string url string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes github_user GithubUser If the changelog entry has no GitHub user, a placeholder is generated. message string? Entry message in Markdown format. Embedded HTML is allowed. message_html string? Entry message in HTML format.
ChatChannel
Represents an individual chat «channel» in the game.
Channel Types
Type Permission Check for Joining/Messaging PUBLIC PRIVATE is player in the allowed groups? (channel.allowed_groups) MULTIPLAYER is player currently in the mp game? SPECTATOR TEMPORARY deprecated PM see below (user_channels) GROUP is player in channel? (user_channels)
For PMs, two factors are taken into account:
ChatMessage
Represents an individual Message within a ChatChannel.
Field Type Description message_id number unique identifier for message sender_id number user_id of the sender channel_id number channel_id of where the message was sent timestamp string when the message was sent, ISO-8601 content string message content is_action boolean was this an action? i.e. /me dances sender UserCompact embedded UserCompact object to save additional api lookups
Comment
Represents an single comment.
Field Type Description commentable_id number ID of the object the comment is attached to commentable_type string type of object the comment is attached to created_at string ISO 8601 date deleted_at string? ISO 8601 date if the comment was deleted; null, otherwise edited_at string? ISO 8601 date if the comment was edited; null, otherwise edited_by_id number? user id of the user that edited the post; null, otherwise id number the ID of the comment legacy_name string? username displayed on legacy comments message string? markdown of the comment’s content message_html string? html version of the comment’s content parent_id number? ID of the comment’s parent pinned boolean Pin status of the comment replies_count number number of replies to the comment updated_at string ISO 8601 date user_id number user ID of the poster votes_count number number of votes
CommentBundle
Comments and related data.
Field Type Description commentable_meta CommentableMeta[] ID of the object the comment is attached to comments Comment[] Array of comments ordered according to sort ; cursor Cursor has_more boolean If there are more comments or replies available has_more_id number? included_comments Comment[] Related comments; e.g. parent comments and nested replies pinned_comments Comment[]? Pinned comments sort string one of the CommentSort types top_level_count number? Number of comments at the top level. Not returned for replies. total number? Total number of comments. Not retuned for replies. user_follow boolean is the current user watching the comment thread? user_votes number[] IDs of the comments in the bundle the current user has upvoted users UserCompact[] array of users related to the comments
CommentSort
Type Sort Fields new created_at (descending), id (descending) old created_at (ascending), id (ascending) top votes_count (descending), created_at (descending), id (descending)
Building cursor for comments listing
The returned response will be for comments after the specified sort fields.
For example, use last loaded comment for the fields value to load more comments. Also make sure to use same sort and parent_id values.
CommentableMeta
Metadata of the object that a comment is attached to.
Field Type Description id number the ID of the object title string display title type string the type of the object url string url of the object
CurrentUserAttributes
An object listing various related permissions and states for the current user, related to the object it is attached to.
BeatmapsetDiscussionPermissions
TODO: needs a better name.
Name Description can_destroy Can delete the discussion. can_reopen Can reopen the discussion. can_moderate_kudosu Can allow or deny kudosu. can_resolve Can resolve the discussion. vote_score Current vote given to the discussion.
ChatChannelUserAttributes
Name Type Description can_message boolean Can send messages to this channel. can_message_error string? Reason messages cannot be sent to this channel last_read_id number message_id of last message read.
Cursor
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.
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
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-07-06
2022-06-08
2021-10-28
2021-09-01
2021-08-11
2021-06-14
2021-06-09
2021-04-20
2021-02-25
2020-09-08
2020-08-28
2020-05-01
2020-02-18
2019-10-09
2019-07-18
Endpoint
Base URL
The base URL is: https://osu.ppy.sh/api/[version]/
API Versions
This is combined with the base endpoint to determine where requests should be sent.
Version Status v2 current (not yet public, consider unstable and expect breaking changes) v1 legacy api provided by the old site, will be deprecated soon
Authentication
Routes marked with the OAuth label require a valid OAuth2 token for access.
More information about applications you have registered and granted permissions to can be found here.
The API supports the following grant types:
Before you can use the osu!api, you will need to
Registering an OAuth application
Before you can get an OAuth token, you will need to register an OAuth application on your account settings page
To register an OAuth application you will need to provide the:
Name Description Application Name This is the name that will be visible to users of your application. The name of your application cannot be changed. Application Callback URL The URL in your application where users will be sent after authorization.
The Application Callback URL is required when for using Authorization Codes. This may be left blank if you are only using Client Credentials Grants.
Your new OAuth application will have a Client ID and Client Secret ; the Client Secret is like a password for your OAuth application, it should be kept private and do not share it with anyone else.
Authorization Code Grant
The flow to authorize users for your application is:
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:
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:
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.
Make sure to replace <> 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:
Name Description chat.write Allows sending chat messages on a user’s behalf. delegate Allows acting as the owner of a client; only available for Client Credentials Grant. forum.write Allows creating and editing forum posts on a user’s behalf. friends.read Allows reading of the user’s friend list. identify Allows reading of the public profile of the user ( /me ). public Allows reading of publicly available data on behalf of the user.
identify is the default scope for the Authorization Code Grant and always implicitly provided. The Client Credentials Grant does not currently have any default scopes.
Routes marked with lazer are intended for use by the osu!lazer client and not currently available for use with Authorization Code or Client Credentials grants.
Using the chat.write scope requires either
Managing OAuth applications
Your account settings page will show your registered OAuth applications, and all the OAuth applications you have granted permissions to.
Reset Client Secret
You can generate a new Client Secret by choosing to «Reset client secret», however, this will disable all access tokens issued for the application.
Beatmaps
Lookup Beatmap
Response format
Get a User Beatmap score
Return a User’s score on a Beatmap
Response Format
The position returned depends on the requested mode and mods.
Get a User Beatmap scores
Return a User’s scores on a Beatmap
Response Format
Get Beatmap scores
Returns the top scores for a beatmap
Response Format
Get Beatmap scores (temp)
Returns the top scores for a beatmap from newer client.
This is a temporary endpoint.
Response Format
Get Beatmaps
Returns list of beatmaps.
Response format
Field Type Description beatmaps BeatmapCompact[] Includes: beatmapset (with ratings), failtimes, max_combo.
Get Beatmap
Gets beatmap data for the specified beatmap ID.
Response format
Returns Beatmap object. Following attributes are included in the response object when applicable,
Attribute Notes beatmapset Includes ratings property. failtimes max_combo
Get Beatmap Attributes
Returns difficulty attributes of beatmap with specific mode and mods combination.
Response format
Beatmapset Discussions
Get Beatmapset Discussion Posts
Returns the posts of beatmapset discussions.
Response Format
Get Beatmapset Discussion Votes
Returns the votes given to beatmapset discussions.
Response Format
Get Beatmapset Discussions
Returns a list of beatmapset discussions.
Response Format
Changelog
Get Changelog Build
Returns details of the specified build.
Response Format
Get Changelog Listing
Returns a listing of update streams, builds, and changelog entries.
Response Format
Lookup Changelog Build
Returns details of the specified build.
Response Format
Create New PM
This endpoint allows you to create a new PM channel.
Response Format
Field Type new_channel_id channel_id of newly created ChatChannel presence array of ChatChannel message the sent ChatMessage
This endpoint will only allow the creation of PMs initially, group chat support will come later.
Get Updates
This endpoint returns new messages since the given message_id along with updated channel ‘presence’ data.
Response Format
Get Channel Messages
This endpoint returns the chat messages for a specific channel.
Response Format
Returns an array of ChatMessage
Send Message to Channel
This endpoint returns the chat messages for a specific channel.
Response Format
Join Channel
This endpoint allows you to join a public or multiplayer channel.
Response Format
Returns the joined ChatChannel.
Leave Channel
This endpoint allows you to leave a public channel.
Response Format
Mark Channel as Read
Response Format
Get Channel List
This endpoint returns a list of all joinable public channels.
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.
Response Format
Returns ChatChannel with recent_messages attribute. Note that in the case of PM s, 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.
Response Format
Field Type Description channel ChatChannel users UserCompact Users are only visible for PM channels.
Comments
Get Comments
Returns a list comments and their replies up to 2 levels deep.
Response Format
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.
Response Format
Get a Comment
Gets a comment and its replies up to 2 levels deep.
Response Format
Edit Comment
Edit an existing comment.
Response Format
Delete Comment
Deletes the specified comment.
Response Format
Add Comment vote
Upvotes a comment.
Response Format
Remove Comment vote
Un-upvotes a comment.
Response Format
Forum
Reply Topic
Create a post replying to the specified topic.
Response Format
ForumPost with body included.
Create Topic
Create a new topic.
Response Format
Get Topic and Posts
Get topic and its posts.
Response Format
Edit Topic
Edit topic. Only title can be edited through this endpoint.
Response Format
Edit Post
Edit specified forum post.
Response Format
ForumPost with body included.
Search
Searches users and wiki pages.
Response Format
SearchResult
Multiplayer
Get User High Score
Returns detail of highest score of specified user and the surrounding scores.
Response Format
Get Scores
Returns a list of scores for specified playlist item.
Response Format
Get a Score
Returns detail of specified score and the surrounding scores.
Response Format
Get News Listing
Returns a list of news posts and related metadata.
Response Format
Get News Post
Returns details of the specified news post.
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.
Response Format
Returns an object containing Notification and other related attributes.
Field Type has_more boolean whether or not there are more notifications notifications array of Notification unread_count total unread notifications notification_endpoint url to connect to websocket server
Mark Notifications as Read
This endpoint allows you to mark notifications read.
Response Format
OAuth Tokens
Revoke current token
Revokes currently authenticated token.
Ranking
Get Ranking
Gets the current ranking for the specified type and game mode.
Response Format
Get Spotlights
Gets the list of spotlights.
Response Format
Undocumented
/beatmaps//solo/scores
/beatmaps//solo/scores//beatmapsets/events
/beatmapsets//favourites
/chat/presence
/matches
/matches//rooms//rooms//users//rooms//users//rooms//leaderboard
/rooms//playlist//scores
/rooms//playlist//scores//reports
/rooms
/rooms//seasonal-backgrounds
/scores///download
/scores///beatmapsets/search//beatmapsets/lookup
/beatmapsets//friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
Similar to Get User but with authenticated user (token owner) as user id.
Response format
Additionally, statistics_rulesets is included, containing statistics for all rulesets.
Get User Kudosu
Returns kudosu history.
Response format
Get User Scores
This endpoint returns the scores of specified user.
Response format
Array of Score. Following attributes are included in the response object when applicable.
Get User Beatmaps
Returns the beatmaps of specified user.
Type Notes favourite graveyard loved most_played pending Previously unranked ranked Previously ranked_and_approved
Response format
Array of BeatmapPlaycount when type is most_played ; array of Beatmapset, otherwise.
Get User Recent Activity
Returns recent activity.
Response format
Get User
This endpoint returns the detail of specified user.
Response format
Returns User object. The following optional attributes on UserCompact are included:
Get Users
Returns list of users.
Response format
Field Type Description users UserCompact[] Includes: country, cover, groups, statistics_rulesets.
Get Wiki Page
The wiki article or image data.
Response Format
Notification Websocket
Connection
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:
Field Type Description event string See below
logout event
Server will disconnect session after sending this event so don’t try to reconnect.
Field Type Description event string logout
new event
New notification. See Notification object for notification types.
Field Type Description event string new data Notification
read event
Notification has been read.
Field Type Description event string read ids number[] id of Notifications which are read
Object Structures
Beatmap
Represent a beatmap. This extends BeatmapCompact with additional attributes.
Field Type Description accuracy float ar float beatmapset_id integer bpm float? convert boolean count_circles integer count_sliders integer count_spinners integer cs float deleted_at Timestamp? drain float hit_length integer is_scoreable boolean last_updated Timestamp mode_int integer passcount integer playcount integer ranked integer See Rank status for list of possible values. url string
BeatmapCompact
Represent a beatmap.
Field Type Description beatmapset_id integer difficulty_rating float id integer mode GameMode status string See Rank status for list of possible values. total_length integer user_id integer version string
Field Type Description beatmapset Beatmapset|BeatmapsetCompact|null Beatmapset for Beatmap object, BeatmapsetCompact for BeatmapCompact object. null if the beatmap doesn’t have associated beatmapset (e.g. deleted). checksum string? failtimes Failtimes max_combo integer
Failtimes
All fields are optional but there’s always at least one field returned.
Field Type Description exit integer[]? Array of length 100. fail integer[]? Array of length 100.
BeatmapDifficultyAttributes
Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.
Field Type max_combo integer star_rating float
Field Type aim_difficulty float approach_rate float flashlight_difficulty float overall_difficulty float slider_factor float speed_difficulty float
taiko
Field Type stamina_difficulty float rhythm_difficulty float colour_difficulty float approach_rate float great_hit_window float
fruits
mania
Field Type great_hit_window float score_multiplier float
BeatmapPlaycount
Represent the playcount of a beatmap.
Field Type Description beatmap_id number beatmap BeatmapCompact? beatmapset BeatmapsetCompact? count number
BeatmapScores
Field Type Description scores Score[] The list of top scores for the beatmap in descending order. userScore BeatmapUserScore? The score of the current user. This is not returned if the current user does not have a score. Note: will be moved to user_score in the future
BeatmapUserScore
Field Type Description position number The position of the score within the requested beatmap ranking. score Score The details of the score.
Beatmapset
Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.
Field Type Description availability.download_disabled boolean availability.more_information string? bpm float can_be_hyped boolean creator string Username of the mapper at the time of beatmapset creation. discussion_locked boolean hype.current integer hype.required integer is_scoreable boolean last_updated Timestamp legacy_thread_url string? nominations.current integer nominations.required integer ranked integer See Rank status for list of possible values. ranked_date Timestamp? source string storyboard boolean submitted_date Timestamp? tags string
The following attributes are always included as well:
Field has_favourited
BeatmapsetCompact
Represents a beatmapset.
Field Type Description artist string artist_unicode string covers Covers creator string favourite_count number id number nsfw boolean play_count number preview_url string source string status string title string title_unicode string user_id number video boolean
Those fields are optional.
Field Type Description beatmaps Beatmap[] converts current_user_attributes description discussions events genre has_favourited boolean language nominations ratings recent_favourites related_users user
Covers
Field Type cover string cover@2x string card string card@2x string list string list@2x string slimcover string slimcover@2x string
Rank status
The possible values are denoted either as integer or string.
Integer String -2 graveyard -1 wip 0 pending 1 ranked 2 approved 3 qualified 4 loved
BeatmapsetDiscussion
Represents a Beatmapset modding discussion.
Field Type Description beatmap BeatmapCompact? beatmap_id number? beatmapset BeatmapsetCompact? beatmapset_id number can_be_resolved boolean can_grant_kudosu boolean created_at Timestamp current_user_attributes CurrentUserAttributes deleted_at Timestamp? deleted_by_id number? id number kudosu_denied boolean last_post_at Timestamp message_type MessageType parent_id number? posts BeatmapsetDiscussionPost[]? resolved boolean starting_post BeatmapsetDiscussionPost? timestamp number? updated_at Timestamp user_id number
MessageType
Name Description hype mapper_note praise problem review suggestion
BeatmapsetDiscussionPost
Field Type Description beatmapset_discussion_id number created_at Timestamp deleted_at Timestamp? deleted_by_id number? id number last_editor_id number? message string system boolean updated_at Timestamp user_id number
BeatmapsetDiscussionVote
Field Type Description beatmapset_discussion_id number created_at Timestamp id number score number updated_at Timestamp user_id number
Build
Field Type created_at Timestamp display_version string id number update_stream UpdateStream? users number version string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes changelog_entries ChangelogEntry[] If the build has no changelog entries, a placeholder is generated. versions Versions
Versions
ChangelogEntry
Field Type category string created_at Timestamp? github_pull_request_id number? github_url string? id number? major boolean repository string? title string? type string url string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes github_user GithubUser If the changelog entry has no GitHub user, a placeholder is generated. message string? Entry message in Markdown format. Embedded HTML is allowed. message_html string? Entry message in HTML format.
ChatChannel
Represents an individual chat «channel» in the game.
Channel Types
Type Permission Check for Joining/Messaging PUBLIC PRIVATE is player in the allowed groups? (channel.allowed_groups) MULTIPLAYER is player currently in the mp game? SPECTATOR TEMPORARY deprecated PM see below (user_channels) GROUP is player in channel? (user_channels)
For PMs, two factors are taken into account:
ChatMessage
Represents an individual Message within a ChatChannel.
Field Type Description message_id number unique identifier for message sender_id number user_id of the sender channel_id number channel_id of where the message was sent timestamp string when the message was sent, ISO-8601 content string message content is_action boolean was this an action? i.e. /me dances sender UserCompact embedded UserCompact object to save additional api lookups
Comment
Represents an single comment.
Field Type Description commentable_id number ID of the object the comment is attached to commentable_type string type of object the comment is attached to created_at string ISO 8601 date deleted_at string? ISO 8601 date if the comment was deleted; null, otherwise edited_at string? ISO 8601 date if the comment was edited; null, otherwise edited_by_id number? user id of the user that edited the post; null, otherwise id number the ID of the comment legacy_name string? username displayed on legacy comments message string? markdown of the comment’s content message_html string? html version of the comment’s content parent_id number? ID of the comment’s parent pinned boolean Pin status of the comment replies_count number number of replies to the comment updated_at string ISO 8601 date user_id number user ID of the poster votes_count number number of votes
CommentBundle
Comments and related data.
Field Type Description commentable_meta CommentableMeta[] ID of the object the comment is attached to comments Comment[] Array of comments ordered according to sort ; cursor Cursor has_more boolean If there are more comments or replies available has_more_id number? included_comments Comment[] Related comments; e.g. parent comments and nested replies pinned_comments Comment[]? Pinned comments sort string one of the CommentSort types top_level_count number? Number of comments at the top level. Not returned for replies. total number? Total number of comments. Not retuned for replies. user_follow boolean is the current user watching the comment thread? user_votes number[] IDs of the comments in the bundle the current user has upvoted users UserCompact[] array of users related to the comments
CommentSort
Type Sort Fields new created_at (descending), id (descending) old created_at (ascending), id (ascending) top votes_count (descending), created_at (descending), id (descending)
Building cursor for comments listing
The returned response will be for comments after the specified sort fields.
For example, use last loaded comment for the fields value to load more comments. Also make sure to use same sort and parent_id values.
CommentableMeta
Metadata of the object that a comment is attached to.
Field Type Description id number the ID of the object title string display title type string the type of the object url string url of the object
CurrentUserAttributes
An object listing various related permissions and states for the current user, related to the object it is attached to.
BeatmapsetDiscussionPermissions
TODO: needs a better name.
Name Description can_destroy Can delete the discussion. can_reopen Can reopen the discussion. can_moderate_kudosu Can allow or deny kudosu. can_resolve Can resolve the discussion. vote_score Current vote given to the discussion.
ChatChannelUserAttributes
Name Type Description can_message boolean Can send messages to this channel. can_message_error string? Reason messages cannot be sent to this channel last_read_id number message_id of last message read.
Cursor
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.
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
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-07-06
2022-06-08
2021-10-28
2021-09-01
2021-08-11
2021-06-14
2021-06-09
2021-04-20
2021-02-25
2020-09-08
2020-08-28
2020-05-01
2020-02-18
2019-10-09
2019-07-18
Endpoint
Base URL
The base URL is: https://osu.ppy.sh/api/[version]/
API Versions
This is combined with the base endpoint to determine where requests should be sent.
Version Status v2 current (not yet public, consider unstable and expect breaking changes) v1 legacy api provided by the old site, will be deprecated soon
Authentication
Routes marked with the OAuth label require a valid OAuth2 token for access.
More information about applications you have registered and granted permissions to can be found here.
The API supports the following grant types:
Before you can use the osu!api, you will need to
Registering an OAuth application
Before you can get an OAuth token, you will need to register an OAuth application on your account settings page
To register an OAuth application you will need to provide the:
Name Description Application Name This is the name that will be visible to users of your application. The name of your application cannot be changed. Application Callback URL The URL in your application where users will be sent after authorization.
The Application Callback URL is required when for using Authorization Codes. This may be left blank if you are only using Client Credentials Grants.
Your new OAuth application will have a Client ID and Client Secret ; the Client Secret is like a password for your OAuth application, it should be kept private and do not share it with anyone else.
Authorization Code Grant
The flow to authorize users for your application is:
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:
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:
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.
Make sure to replace <> 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:
Name Description chat.write Allows sending chat messages on a user’s behalf. delegate Allows acting as the owner of a client; only available for Client Credentials Grant. forum.write Allows creating and editing forum posts on a user’s behalf. friends.read Allows reading of the user’s friend list. identify Allows reading of the public profile of the user ( /me ). public Allows reading of publicly available data on behalf of the user.
identify is the default scope for the Authorization Code Grant and always implicitly provided. The Client Credentials Grant does not currently have any default scopes.
Routes marked with lazer are intended for use by the osu!lazer client and not currently available for use with Authorization Code or Client Credentials grants.
Using the chat.write scope requires either
Managing OAuth applications
Your account settings page will show your registered OAuth applications, and all the OAuth applications you have granted permissions to.
Reset Client Secret
You can generate a new Client Secret by choosing to «Reset client secret», however, this will disable all access tokens issued for the application.
Beatmaps
Lookup Beatmap
Response format
Get a User Beatmap score
Return a User’s score on a Beatmap
Response Format
The position returned depends on the requested mode and mods.
Get a User Beatmap scores
Return a User’s scores on a Beatmap
Response Format
Get Beatmap scores
Returns the top scores for a beatmap
Response Format
Get Beatmap scores (temp)
Returns the top scores for a beatmap from newer client.
This is a temporary endpoint.
Response Format
Get Beatmaps
Returns list of beatmaps.
Response format
Field Type Description beatmaps BeatmapCompact[] Includes: beatmapset (with ratings), failtimes, max_combo.
Get Beatmap
Gets beatmap data for the specified beatmap ID.
Response format
Returns Beatmap object. Following attributes are included in the response object when applicable,
Attribute Notes beatmapset Includes ratings property. failtimes max_combo
Get Beatmap Attributes
Returns difficulty attributes of beatmap with specific mode and mods combination.
Response format
Beatmapset Discussions
Get Beatmapset Discussion Posts
Returns the posts of beatmapset discussions.
Response Format
Get Beatmapset Discussion Votes
Returns the votes given to beatmapset discussions.
Response Format
Get Beatmapset Discussions
Returns a list of beatmapset discussions.
Response Format
Changelog
Get Changelog Build
Returns details of the specified build.
Response Format
Get Changelog Listing
Returns a listing of update streams, builds, and changelog entries.
Response Format
Lookup Changelog Build
Returns details of the specified build.
Response Format
Create New PM
This endpoint allows you to create a new PM channel.
Response Format
Field Type new_channel_id channel_id of newly created ChatChannel presence array of ChatChannel message the sent ChatMessage
This endpoint will only allow the creation of PMs initially, group chat support will come later.
Get Updates
This endpoint returns new messages since the given message_id along with updated channel ‘presence’ data.
Response Format
Get Channel Messages
This endpoint returns the chat messages for a specific channel.
Response Format
Returns an array of ChatMessage
Send Message to Channel
This endpoint returns the chat messages for a specific channel.
Response Format
Join Channel
This endpoint allows you to join a public or multiplayer channel.
Response Format
Returns the joined ChatChannel.
Leave Channel
This endpoint allows you to leave a public channel.
Response Format
Mark Channel as Read
Response Format
Get Channel List
This endpoint returns a list of all joinable public channels.
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.
Response Format
Returns ChatChannel with recent_messages attribute. Note that in the case of PM s, 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.
Response Format
Field Type Description channel ChatChannel users UserCompact Users are only visible for PM channels.
Comments
Get Comments
Returns a list comments and their replies up to 2 levels deep.
Response Format
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.
Response Format
Get a Comment
Gets a comment and its replies up to 2 levels deep.
Response Format
Edit Comment
Edit an existing comment.
Response Format
Delete Comment
Deletes the specified comment.
Response Format
Add Comment vote
Upvotes a comment.
Response Format
Remove Comment vote
Un-upvotes a comment.
Response Format
Forum
Reply Topic
Create a post replying to the specified topic.
Response Format
ForumPost with body included.
Create Topic
Create a new topic.
Response Format
Get Topic and Posts
Get topic and its posts.
Response Format
Edit Topic
Edit topic. Only title can be edited through this endpoint.
Response Format
Edit Post
Edit specified forum post.
Response Format
ForumPost with body included.
Search
Searches users and wiki pages.
Response Format
SearchResult
Multiplayer
Get User High Score
Returns detail of highest score of specified user and the surrounding scores.
Response Format
Get Scores
Returns a list of scores for specified playlist item.
Response Format
Get a Score
Returns detail of specified score and the surrounding scores.
Response Format
Get News Listing
Returns a list of news posts and related metadata.
Response Format
Get News Post
Returns details of the specified news post.
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.
Response Format
Returns an object containing Notification and other related attributes.
Field Type has_more boolean whether or not there are more notifications notifications array of Notification unread_count total unread notifications notification_endpoint url to connect to websocket server
Mark Notifications as Read
This endpoint allows you to mark notifications read.
Response Format
OAuth Tokens
Revoke current token
Revokes currently authenticated token.
Ranking
Get Ranking
Gets the current ranking for the specified type and game mode.
Response Format
Get Spotlights
Gets the list of spotlights.
Response Format
Undocumented
/beatmaps//solo/scores
/beatmaps//solo/scores//beatmapsets/events
/beatmapsets//favourites
/chat/presence
/matches
/matches//rooms//rooms//users//rooms//users//rooms//leaderboard
/rooms//playlist//scores
/rooms//playlist//scores//reports
/rooms
/rooms//seasonal-backgrounds
/scores///download
/scores///beatmapsets/search//beatmapsets/lookup
/beatmapsets//friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
Similar to Get User but with authenticated user (token owner) as user id.
Response format
Additionally, statistics_rulesets is included, containing statistics for all rulesets.
Get User Kudosu
Returns kudosu history.
Response format
Get User Scores
This endpoint returns the scores of specified user.
Response format
Array of Score. Following attributes are included in the response object when applicable.
Get User Beatmaps
Returns the beatmaps of specified user.
Type Notes favourite graveyard loved most_played pending Previously unranked ranked Previously ranked_and_approved
Response format
Array of BeatmapPlaycount when type is most_played ; array of Beatmapset, otherwise.
Get User Recent Activity
Returns recent activity.
Response format
Get User
This endpoint returns the detail of specified user.
Response format
Returns User object. The following optional attributes on UserCompact are included:
Get Users
Returns list of users.
Response format
Field Type Description users UserCompact[] Includes: country, cover, groups, statistics_rulesets.
Get Wiki Page
The wiki article or image data.
Response Format
Notification Websocket
Connection
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:
Field Type Description event string See below
logout event
Server will disconnect session after sending this event so don’t try to reconnect.
Field Type Description event string logout
new event
New notification. See Notification object for notification types.
Field Type Description event string new data Notification
read event
Notification has been read.
Field Type Description event string read ids number[] id of Notifications which are read
Object Structures
Beatmap
Represent a beatmap. This extends BeatmapCompact with additional attributes.
Field Type Description accuracy float ar float beatmapset_id integer bpm float? convert boolean count_circles integer count_sliders integer count_spinners integer cs float deleted_at Timestamp? drain float hit_length integer is_scoreable boolean last_updated Timestamp mode_int integer passcount integer playcount integer ranked integer See Rank status for list of possible values. url string
BeatmapCompact
Represent a beatmap.
Field Type Description beatmapset_id integer difficulty_rating float id integer mode GameMode status string See Rank status for list of possible values. total_length integer user_id integer version string
Field Type Description beatmapset Beatmapset|BeatmapsetCompact|null Beatmapset for Beatmap object, BeatmapsetCompact for BeatmapCompact object. null if the beatmap doesn’t have associated beatmapset (e.g. deleted). checksum string? failtimes Failtimes max_combo integer
Failtimes
All fields are optional but there’s always at least one field returned.
Field Type Description exit integer[]? Array of length 100. fail integer[]? Array of length 100.
BeatmapDifficultyAttributes
Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.
Field Type max_combo integer star_rating float
Field Type aim_difficulty float approach_rate float flashlight_difficulty float overall_difficulty float slider_factor float speed_difficulty float
taiko
Field Type stamina_difficulty float rhythm_difficulty float colour_difficulty float approach_rate float great_hit_window float
fruits
mania
Field Type great_hit_window float score_multiplier float
BeatmapPlaycount
Represent the playcount of a beatmap.
Field Type Description beatmap_id number beatmap BeatmapCompact? beatmapset BeatmapsetCompact? count number
BeatmapScores
Field Type Description scores Score[] The list of top scores for the beatmap in descending order. userScore BeatmapUserScore? The score of the current user. This is not returned if the current user does not have a score. Note: will be moved to user_score in the future
BeatmapUserScore
Field Type Description position number The position of the score within the requested beatmap ranking. score Score The details of the score.
Beatmapset
Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.
Field Type Description availability.download_disabled boolean availability.more_information string? bpm float can_be_hyped boolean creator string Username of the mapper at the time of beatmapset creation. discussion_locked boolean hype.current integer hype.required integer is_scoreable boolean last_updated Timestamp legacy_thread_url string? nominations.current integer nominations.required integer ranked integer See Rank status for list of possible values. ranked_date Timestamp? source string storyboard boolean submitted_date Timestamp? tags string
The following attributes are always included as well:
Field has_favourited
BeatmapsetCompact
Represents a beatmapset.
Field Type Description artist string artist_unicode string covers Covers creator string favourite_count number id number nsfw boolean play_count number preview_url string source string status string title string title_unicode string user_id number video boolean
Those fields are optional.
Field Type Description beatmaps Beatmap[] converts current_user_attributes description discussions events genre has_favourited boolean language nominations ratings recent_favourites related_users user
Covers
Field Type cover string cover@2x string card string card@2x string list string list@2x string slimcover string slimcover@2x string
Rank status
The possible values are denoted either as integer or string.
Integer String -2 graveyard -1 wip 0 pending 1 ranked 2 approved 3 qualified 4 loved
BeatmapsetDiscussion
Represents a Beatmapset modding discussion.
Field Type Description beatmap BeatmapCompact? beatmap_id number? beatmapset BeatmapsetCompact? beatmapset_id number can_be_resolved boolean can_grant_kudosu boolean created_at Timestamp current_user_attributes CurrentUserAttributes deleted_at Timestamp? deleted_by_id number? id number kudosu_denied boolean last_post_at Timestamp message_type MessageType parent_id number? posts BeatmapsetDiscussionPost[]? resolved boolean starting_post BeatmapsetDiscussionPost? timestamp number? updated_at Timestamp user_id number
MessageType
Name Description hype mapper_note praise problem review suggestion
BeatmapsetDiscussionPost
Field Type Description beatmapset_discussion_id number created_at Timestamp deleted_at Timestamp? deleted_by_id number? id number last_editor_id number? message string system boolean updated_at Timestamp user_id number
BeatmapsetDiscussionVote
Field Type Description beatmapset_discussion_id number created_at Timestamp id number score number updated_at Timestamp user_id number
Build
Field Type created_at Timestamp display_version string id number update_stream UpdateStream? users number version string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes changelog_entries ChangelogEntry[] If the build has no changelog entries, a placeholder is generated. versions Versions
Versions
ChangelogEntry
Field Type category string created_at Timestamp? github_pull_request_id number? github_url string? id number? major boolean repository string? title string? type string url string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes github_user GithubUser If the changelog entry has no GitHub user, a placeholder is generated. message string? Entry message in Markdown format. Embedded HTML is allowed. message_html string? Entry message in HTML format.
ChatChannel
Represents an individual chat «channel» in the game.
Channel Types
Type Permission Check for Joining/Messaging PUBLIC PRIVATE is player in the allowed groups? (channel.allowed_groups) MULTIPLAYER is player currently in the mp game? SPECTATOR TEMPORARY deprecated PM see below (user_channels) GROUP is player in channel? (user_channels)
For PMs, two factors are taken into account:
ChatMessage
Represents an individual Message within a ChatChannel.
Field Type Description message_id number unique identifier for message sender_id number user_id of the sender channel_id number channel_id of where the message was sent timestamp string when the message was sent, ISO-8601 content string message content is_action boolean was this an action? i.e. /me dances sender UserCompact embedded UserCompact object to save additional api lookups
Comment
Represents an single comment.
Field Type Description commentable_id number ID of the object the comment is attached to commentable_type string type of object the comment is attached to created_at string ISO 8601 date deleted_at string? ISO 8601 date if the comment was deleted; null, otherwise edited_at string? ISO 8601 date if the comment was edited; null, otherwise edited_by_id number? user id of the user that edited the post; null, otherwise id number the ID of the comment legacy_name string? username displayed on legacy comments message string? markdown of the comment’s content message_html string? html version of the comment’s content parent_id number? ID of the comment’s parent pinned boolean Pin status of the comment replies_count number number of replies to the comment updated_at string ISO 8601 date user_id number user ID of the poster votes_count number number of votes
CommentBundle
Comments and related data.
Field Type Description commentable_meta CommentableMeta[] ID of the object the comment is attached to comments Comment[] Array of comments ordered according to sort ; cursor Cursor has_more boolean If there are more comments or replies available has_more_id number? included_comments Comment[] Related comments; e.g. parent comments and nested replies pinned_comments Comment[]? Pinned comments sort string one of the CommentSort types top_level_count number? Number of comments at the top level. Not returned for replies. total number? Total number of comments. Not retuned for replies. user_follow boolean is the current user watching the comment thread? user_votes number[] IDs of the comments in the bundle the current user has upvoted users UserCompact[] array of users related to the comments
CommentSort
Type Sort Fields new created_at (descending), id (descending) old created_at (ascending), id (ascending) top votes_count (descending), created_at (descending), id (descending)
Building cursor for comments listing
The returned response will be for comments after the specified sort fields.
For example, use last loaded comment for the fields value to load more comments. Also make sure to use same sort and parent_id values.
CommentableMeta
Metadata of the object that a comment is attached to.
Field Type Description id number the ID of the object title string display title type string the type of the object url string url of the object
CurrentUserAttributes
An object listing various related permissions and states for the current user, related to the object it is attached to.
BeatmapsetDiscussionPermissions
TODO: needs a better name.
Name Description can_destroy Can delete the discussion. can_reopen Can reopen the discussion. can_moderate_kudosu Can allow or deny kudosu. can_resolve Can resolve the discussion. vote_score Current vote given to the discussion.
ChatChannelUserAttributes
Name Type Description can_message boolean Can send messages to this channel. can_message_error string? Reason messages cannot be sent to this channel last_read_id number message_id of last message read.
Cursor
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.
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
osu!api open beta
Нет аккаунта?
osu!api open beta
I’ve had an API available for a while but until now it has been on a private on-request basis. In order to try and make developing third party services which expand and support osu!, I have added an API key setup and started to document the API.
Documentation will be expanded as I find time to do so! If anyone currently using the API is able to help expand the documentation then please do.
comentarinformal wrote:
Before I spam it with requests that might not exist, is there anything to get user’s information?
(Also, is there anything to login users from this page in other places?)
There is /api/get_user
Gonna write an entry with the information I have about it.
Is there a fair use limit? (e.g. no more than XX requests per day)
For get_user, I suppose there is a mode parameter for getting user information for Taiko, CtB and osu!mania? Or do I have to file an issue in GitHub? Nevermind, I found it, the parameter to add is called «m» I have edited the GitHub wiki.
Oh well. I have some questions:
Are only the beatmap and user endpoints available?
The parameter «since» in /get_beatmap how I need to pass the time on it? UTC or unix timestamp?
Do I need to pass the key on the wiki’s API too?
Edit: What the countX values mean? Number of beatmaps?
comentarinformal wrote:
Before I spam it with requests that might not exist, is there anything to get user’s information?
(Also, is there anything to login users from this page in other places?)
I guess I’ll update my userbar too when I find some time.
Damnae wrote:
I guess I’ll update my userbar too when I find some time.
I registered it for osu!userbar, but I also use it for my «Big ugly white signature», they are not on the same webserver, but it works fine
I belive only you and peppy can see the name you used, too.
(Yes I took my lazyness off, it was not that long to update ^^)
@Repflez: I tried using your API-powered signature and I get something weird.
Since I only aim for SS, I have 100% Accuracy all the time, and the Accuracy display is weird.
(I now know that despite having all-SS records, the note hit count for getting 50s and 100s are still counted all the time )
Winshley wrote:
@Repflez: I tried using your API-powered signature and I get something weird.
Since I only aim for SS, I have 100% Accuracy all the time, and the Accuracy display is weird.
(I now know that despite having all-SS records, the note hit count for getting 50s and 100s are still counted all the time )
So that’s what the CountX values mean. Thanks for that. I already went and changed the accuracy to show a centered «100% Accuracy» if it’s 100. Forget that. I ditched the bar on it and used the extra space for showing the PP.
(I love how the 300 count ended overlaping the border)
Repflez wrote:
So that’s what the CountX values mean. Thanks for that.
Yeah. At first I thought that there was something wrong with the API showing 50s and 100s despite having 100% Accuracy, until I actually calculated all 300s + 100s + 50s = «Total Hits» on our profile.
About the 300 overlap though, it does need some fix:
When you reached 10 millions of 300 hits, the last number is cut off. Cookiezi has 17 millions of 300 hits.
I’m not sure how the level bar breaking happens though. I was thinking that it probably because I don’t have any ranked score on osu!mania?
[Archived] getting osu! api token
Нет аккаунта?
[Archived] getting osu! api token
here is the website I am currently using this for https://osu-api-crap.minecreeper0913.repl.co
well since the project I am using is all python and not javascript I am using a new tab browser to just test it and so far the code I am using is
url = («https://osu.ppy.sh/oauth/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=%s» % (code))
the &code=%s is basically just grabbing the code that has been given back by oauth and using that as the url, when I am testing it though I am actually using my code
Never share your client secret, it’s secret for a reason. I would recommend resetting it ASAP.
Are you just typing that URL into your browser or are you actually sending it as a post request with whatever python code you have? Typing the URL into your browser won’t work.
The token endpoint takes the parameters in the body of the request, not as query parameters. You are also missing some parameters, like redirect_uri and grant_type.
If you are using python’s requests library, you can do something like this:
Might have some syntax errors because I wrote that from memory and didn’t check anything in an IDE or by running it.
You can try without specifying the content type in your headers, it might work without it. Very simply, the content type header describes what type of content or data is being sent. As far as I recall, the server is expecting that content type but I could be wrong.
now starting to realize that I might have done this a bit wrong, this is the first time I have used an API for something so everything I am doing is new to me.
So the first thing that is happening is that you press the login to link your osu API to the website, then it grabs your code and redirects you to the home website with the code in the url for example http://www.website.com/code=j9838r9y82g9438gh8243hg384hg, and it is supposed to use that, but when in testing it just returns favicon.ico, and I don’t know what that is or means so I might have to change my get request, another issue is but how would I make it get that auth code?
I don’t know anything about the project you are working on, so unfortunately I don’t think I can really answer any of the questions you’re asking.
I don’t know what you mean by a favicon being returned and I also don’t know what you are using the handle the backend of your site, so I can’t specifically tell you how to grab the code. Whatever you are using should have some way of getting query parameters from the URL.
Oauth2 is a very standardized and should be nearly the same everywhere that uses it. osu! is no exception. I would highly recommend looking up and reading about the authorization code flow that you are trying to use here. There should be a ton of resources and maybe a few code examples as well.
There might not be any videos specific to osu!’s API, but there are definitely Oauth2 tutorial videos and examples out there in probably every programming language, which is what you are dealing with right now.
For example, here is a video I found after a quick Google search that is using Python. I can’t fully comment on its quality since I just skimmed through it, but the general flow that the creator of the video goes over seems like it will at least cover how OAuth2 works in general, even if it’s not in the context of osu!’s API.
And even if you don’t really like reading, there are still some pretty good resources you can use that might help in addition to watching a video. Like this and this for example. Again, I’ve only skimmed through these, but they also seem to be pretty good.
here is the code I use:
NOTE I did not actually use SECRET as the secret I have it as SECRET because its secret
/reports
/rooms
/rooms//seasonal-backgrounds
/scores///download
/scores///beatmapsets/search//beatmapsets/lookup
/beatmapsets//friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
Similar to Get User but with authenticated user (token owner) as user id.
Response format
Additionally, statistics_rulesets is included, containing statistics for all rulesets.
Get User Kudosu
Returns kudosu history.
Response format
Get User Scores
This endpoint returns the scores of specified user.
Response format
Array of Score. Following attributes are included in the response object when applicable.
Get User Beatmaps
Returns the beatmaps of specified user.
Type Notes favourite graveyard loved most_played pending Previously unranked ranked Previously ranked_and_approved
Response format
Array of BeatmapPlaycount when type is most_played ; array of Beatmapset, otherwise.
Get User Recent Activity
Returns recent activity.
Response format
Get User
This endpoint returns the detail of specified user.
Response format
Returns User object. The following optional attributes on UserCompact are included:
Get Users
Returns list of users.
Response format
Field Type Description users UserCompact[] Includes: country, cover, groups, statistics_rulesets.
Get Wiki Page
The wiki article or image data.
Response Format
Notification Websocket
Connection
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:
Field Type Description event string See below
logout event
Server will disconnect session after sending this event so don’t try to reconnect.
Field Type Description event string logout
new event
New notification. See Notification object for notification types.
Field Type Description event string new data Notification
read event
Notification has been read.
Field Type Description event string read ids number[] id of Notifications which are read
Object Structures
Beatmap
Represent a beatmap. This extends BeatmapCompact with additional attributes.
Field Type Description accuracy float ar float beatmapset_id integer bpm float? convert boolean count_circles integer count_sliders integer count_spinners integer cs float deleted_at Timestamp? drain float hit_length integer is_scoreable boolean last_updated Timestamp mode_int integer passcount integer playcount integer ranked integer See Rank status for list of possible values. url string
BeatmapCompact
Represent a beatmap.
Field Type Description beatmapset_id integer difficulty_rating float id integer mode GameMode status string See Rank status for list of possible values. total_length integer user_id integer version string
Field Type Description beatmapset Beatmapset|BeatmapsetCompact|null Beatmapset for Beatmap object, BeatmapsetCompact for BeatmapCompact object. null if the beatmap doesn’t have associated beatmapset (e.g. deleted). checksum string? failtimes Failtimes max_combo integer
Failtimes
All fields are optional but there’s always at least one field returned.
Field Type Description exit integer[]? Array of length 100. fail integer[]? Array of length 100.
BeatmapDifficultyAttributes
Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.
Field Type max_combo integer star_rating float
Field Type aim_difficulty float approach_rate float flashlight_difficulty float overall_difficulty float slider_factor float speed_difficulty float
taiko
Field Type stamina_difficulty float rhythm_difficulty float colour_difficulty float approach_rate float great_hit_window float
fruits
mania
Field Type great_hit_window float score_multiplier float
BeatmapPlaycount
Represent the playcount of a beatmap.
Field Type Description beatmap_id number beatmap BeatmapCompact? beatmapset BeatmapsetCompact? count number
BeatmapScores
Field Type Description scores Score[] The list of top scores for the beatmap in descending order. userScore BeatmapUserScore? The score of the current user. This is not returned if the current user does not have a score. Note: will be moved to user_score in the future
BeatmapUserScore
Field Type Description position number The position of the score within the requested beatmap ranking. score Score The details of the score.
Beatmapset
Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.
Field Type Description availability.download_disabled boolean availability.more_information string? bpm float can_be_hyped boolean creator string Username of the mapper at the time of beatmapset creation. discussion_locked boolean hype.current integer hype.required integer is_scoreable boolean last_updated Timestamp legacy_thread_url string? nominations.current integer nominations.required integer ranked integer See Rank status for list of possible values. ranked_date Timestamp? source string storyboard boolean submitted_date Timestamp? tags string
The following attributes are always included as well:
Field has_favourited
BeatmapsetCompact
Represents a beatmapset.
Field Type Description artist string artist_unicode string covers Covers creator string favourite_count number id number nsfw boolean play_count number preview_url string source string status string title string title_unicode string user_id number video boolean
Those fields are optional.
Field Type Description beatmaps Beatmap[] converts current_user_attributes description discussions events genre has_favourited boolean language nominations ratings recent_favourites related_users user
Covers
Field Type cover string cover@2x string card string card@2x string list string list@2x string slimcover string slimcover@2x string
Rank status
The possible values are denoted either as integer or string.
Integer String -2 graveyard -1 wip 0 pending 1 ranked 2 approved 3 qualified 4 loved
BeatmapsetDiscussion
Represents a Beatmapset modding discussion.
Field Type Description beatmap BeatmapCompact? beatmap_id number? beatmapset BeatmapsetCompact? beatmapset_id number can_be_resolved boolean can_grant_kudosu boolean created_at Timestamp current_user_attributes CurrentUserAttributes deleted_at Timestamp? deleted_by_id number? id number kudosu_denied boolean last_post_at Timestamp message_type MessageType parent_id number? posts BeatmapsetDiscussionPost[]? resolved boolean starting_post BeatmapsetDiscussionPost? timestamp number? updated_at Timestamp user_id number
MessageType
Name Description hype mapper_note praise problem review suggestion
BeatmapsetDiscussionPost
Field Type Description beatmapset_discussion_id number created_at Timestamp deleted_at Timestamp? deleted_by_id number? id number last_editor_id number? message string system boolean updated_at Timestamp user_id number
BeatmapsetDiscussionVote
Field Type Description beatmapset_discussion_id number created_at Timestamp id number score number updated_at Timestamp user_id number
Build
Field Type created_at Timestamp display_version string id number update_stream UpdateStream? users number version string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes changelog_entries ChangelogEntry[] If the build has no changelog entries, a placeholder is generated. versions Versions
Versions
ChangelogEntry
Field Type category string created_at Timestamp? github_pull_request_id number? github_url string? id number? major boolean repository string? title string? type string url string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes github_user GithubUser If the changelog entry has no GitHub user, a placeholder is generated. message string? Entry message in Markdown format. Embedded HTML is allowed. message_html string? Entry message in HTML format.
ChatChannel
Represents an individual chat «channel» in the game.
Channel Types
Type Permission Check for Joining/Messaging PUBLIC PRIVATE is player in the allowed groups? (channel.allowed_groups) MULTIPLAYER is player currently in the mp game? SPECTATOR TEMPORARY deprecated PM see below (user_channels) GROUP is player in channel? (user_channels)
For PMs, two factors are taken into account:
ChatMessage
Represents an individual Message within a ChatChannel.
Field Type Description message_id number unique identifier for message sender_id number user_id of the sender channel_id number channel_id of where the message was sent timestamp string when the message was sent, ISO-8601 content string message content is_action boolean was this an action? i.e. /me dances sender UserCompact embedded UserCompact object to save additional api lookups
Comment
Represents an single comment.
Field Type Description commentable_id number ID of the object the comment is attached to commentable_type string type of object the comment is attached to created_at string ISO 8601 date deleted_at string? ISO 8601 date if the comment was deleted; null, otherwise edited_at string? ISO 8601 date if the comment was edited; null, otherwise edited_by_id number? user id of the user that edited the post; null, otherwise id number the ID of the comment legacy_name string? username displayed on legacy comments message string? markdown of the comment’s content message_html string? html version of the comment’s content parent_id number? ID of the comment’s parent pinned boolean Pin status of the comment replies_count number number of replies to the comment updated_at string ISO 8601 date user_id number user ID of the poster votes_count number number of votes
CommentBundle
Comments and related data.
Field Type Description commentable_meta CommentableMeta[] ID of the object the comment is attached to comments Comment[] Array of comments ordered according to sort ; cursor Cursor has_more boolean If there are more comments or replies available has_more_id number? included_comments Comment[] Related comments; e.g. parent comments and nested replies pinned_comments Comment[]? Pinned comments sort string one of the CommentSort types top_level_count number? Number of comments at the top level. Not returned for replies. total number? Total number of comments. Not retuned for replies. user_follow boolean is the current user watching the comment thread? user_votes number[] IDs of the comments in the bundle the current user has upvoted users UserCompact[] array of users related to the comments
CommentSort
Type Sort Fields new created_at (descending), id (descending) old created_at (ascending), id (ascending) top votes_count (descending), created_at (descending), id (descending)
Building cursor for comments listing
The returned response will be for comments after the specified sort fields.
For example, use last loaded comment for the fields value to load more comments. Also make sure to use same sort and parent_id values.
CommentableMeta
Metadata of the object that a comment is attached to.
Field Type Description id number the ID of the object title string display title type string the type of the object url string url of the object
CurrentUserAttributes
An object listing various related permissions and states for the current user, related to the object it is attached to.
BeatmapsetDiscussionPermissions
TODO: needs a better name.
Name Description can_destroy Can delete the discussion. can_reopen Can reopen the discussion. can_moderate_kudosu Can allow or deny kudosu. can_resolve Can resolve the discussion. vote_score Current vote given to the discussion.
ChatChannelUserAttributes
Name Type Description can_message boolean Can send messages to this channel. can_message_error string? Reason messages cannot be sent to this channel last_read_id number message_id of last message read.
Cursor
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.
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
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-07-06
2022-06-08
2021-10-28
2021-09-01
2021-08-11
2021-06-14
2021-06-09
2021-04-20
2021-02-25
2020-09-08
2020-08-28
2020-05-01
2020-02-18
2019-10-09
2019-07-18
Endpoint
Base URL
The base URL is: https://osu.ppy.sh/api/[version]/
API Versions
This is combined with the base endpoint to determine where requests should be sent.
Version Status v2 current (not yet public, consider unstable and expect breaking changes) v1 legacy api provided by the old site, will be deprecated soon
Authentication
Routes marked with the OAuth label require a valid OAuth2 token for access.
More information about applications you have registered and granted permissions to can be found here.
The API supports the following grant types:
Before you can use the osu!api, you will need to
Registering an OAuth application
Before you can get an OAuth token, you will need to register an OAuth application on your account settings page
To register an OAuth application you will need to provide the:
Name Description Application Name This is the name that will be visible to users of your application. The name of your application cannot be changed. Application Callback URL The URL in your application where users will be sent after authorization.
The Application Callback URL is required when for using Authorization Codes. This may be left blank if you are only using Client Credentials Grants.
Your new OAuth application will have a Client ID and Client Secret ; the Client Secret is like a password for your OAuth application, it should be kept private and do not share it with anyone else.
Authorization Code Grant
The flow to authorize users for your application is:
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:
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:
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.
Make sure to replace <> 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:
Name Description chat.write Allows sending chat messages on a user’s behalf. delegate Allows acting as the owner of a client; only available for Client Credentials Grant. forum.write Allows creating and editing forum posts on a user’s behalf. friends.read Allows reading of the user’s friend list. identify Allows reading of the public profile of the user ( /me ). public Allows reading of publicly available data on behalf of the user.
identify is the default scope for the Authorization Code Grant and always implicitly provided. The Client Credentials Grant does not currently have any default scopes.
Routes marked with lazer are intended for use by the osu!lazer client and not currently available for use with Authorization Code or Client Credentials grants.
Using the chat.write scope requires either
Managing OAuth applications
Your account settings page will show your registered OAuth applications, and all the OAuth applications you have granted permissions to.
Reset Client Secret
You can generate a new Client Secret by choosing to «Reset client secret», however, this will disable all access tokens issued for the application.
Beatmaps
Lookup Beatmap
Response format
Get a User Beatmap score
Return a User’s score on a Beatmap
Response Format
The position returned depends on the requested mode and mods.
Get a User Beatmap scores
Return a User’s scores on a Beatmap
Response Format
Get Beatmap scores
Returns the top scores for a beatmap
Response Format
Get Beatmap scores (temp)
Returns the top scores for a beatmap from newer client.
This is a temporary endpoint.
Response Format
Get Beatmaps
Returns list of beatmaps.
Response format
Field Type Description beatmaps BeatmapCompact[] Includes: beatmapset (with ratings), failtimes, max_combo.
Get Beatmap
Gets beatmap data for the specified beatmap ID.
Response format
Returns Beatmap object. Following attributes are included in the response object when applicable,
Attribute Notes beatmapset Includes ratings property. failtimes max_combo
Get Beatmap Attributes
Returns difficulty attributes of beatmap with specific mode and mods combination.
Response format
Beatmapset Discussions
Get Beatmapset Discussion Posts
Returns the posts of beatmapset discussions.
Response Format
Get Beatmapset Discussion Votes
Returns the votes given to beatmapset discussions.
Response Format
Get Beatmapset Discussions
Returns a list of beatmapset discussions.
Response Format
Changelog
Get Changelog Build
Returns details of the specified build.
Response Format
Get Changelog Listing
Returns a listing of update streams, builds, and changelog entries.
Response Format
Lookup Changelog Build
Returns details of the specified build.
Response Format
Create New PM
This endpoint allows you to create a new PM channel.
Response Format
Field Type new_channel_id channel_id of newly created ChatChannel presence array of ChatChannel message the sent ChatMessage
This endpoint will only allow the creation of PMs initially, group chat support will come later.
Get Updates
This endpoint returns new messages since the given message_id along with updated channel ‘presence’ data.
Response Format
Get Channel Messages
This endpoint returns the chat messages for a specific channel.
Response Format
Returns an array of ChatMessage
Send Message to Channel
This endpoint returns the chat messages for a specific channel.
Response Format
Join Channel
This endpoint allows you to join a public or multiplayer channel.
Response Format
Returns the joined ChatChannel.
Leave Channel
This endpoint allows you to leave a public channel.
Response Format
Mark Channel as Read
Response Format
Get Channel List
This endpoint returns a list of all joinable public channels.
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.
Response Format
Returns ChatChannel with recent_messages attribute. Note that in the case of PM s, 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.
Response Format
Field Type Description channel ChatChannel users UserCompact Users are only visible for PM channels.
Comments
Get Comments
Returns a list comments and their replies up to 2 levels deep.
Response Format
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.
Response Format
Get a Comment
Gets a comment and its replies up to 2 levels deep.
Response Format
Edit Comment
Edit an existing comment.
Response Format
Delete Comment
Deletes the specified comment.
Response Format
Add Comment vote
Upvotes a comment.
Response Format
Remove Comment vote
Un-upvotes a comment.
Response Format
Forum
Reply Topic
Create a post replying to the specified topic.
Response Format
ForumPost with body included.
Create Topic
Create a new topic.
Response Format
Get Topic and Posts
Get topic and its posts.
Response Format
Edit Topic
Edit topic. Only title can be edited through this endpoint.
Response Format
Edit Post
Edit specified forum post.
Response Format
ForumPost with body included.
Search
Searches users and wiki pages.
Response Format
SearchResult
Multiplayer
Get User High Score
Returns detail of highest score of specified user and the surrounding scores.
Response Format
Get Scores
Returns a list of scores for specified playlist item.
Response Format
Get a Score
Returns detail of specified score and the surrounding scores.
Response Format
Get News Listing
Returns a list of news posts and related metadata.
Response Format
Get News Post
Returns details of the specified news post.
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.
Response Format
Returns an object containing Notification and other related attributes.
Field Type has_more boolean whether or not there are more notifications notifications array of Notification unread_count total unread notifications notification_endpoint url to connect to websocket server
Mark Notifications as Read
This endpoint allows you to mark notifications read.
Response Format
OAuth Tokens
Revoke current token
Revokes currently authenticated token.
Ranking
Get Ranking
Gets the current ranking for the specified type and game mode.
Response Format
Get Spotlights
Gets the list of spotlights.
Response Format
Undocumented
/beatmaps//solo/scores
/beatmaps//solo/scores//beatmapsets/events
/beatmapsets//favourites
/chat/presence
/matches
/matches//rooms//rooms//users//rooms//users//rooms//leaderboard
/rooms//playlist//scores
/rooms//playlist//scores//reports
/rooms
/rooms//seasonal-backgrounds
/scores///download
/scores///beatmapsets/search//beatmapsets/lookup
/beatmapsets//friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
Similar to Get User but with authenticated user (token owner) as user id.
Response format
Additionally, statistics_rulesets is included, containing statistics for all rulesets.
Get User Kudosu
Returns kudosu history.
Response format
Get User Scores
This endpoint returns the scores of specified user.
Response format
Array of Score. Following attributes are included in the response object when applicable.
Get User Beatmaps
Returns the beatmaps of specified user.
Type Notes favourite graveyard loved most_played pending Previously unranked ranked Previously ranked_and_approved
Response format
Array of BeatmapPlaycount when type is most_played ; array of Beatmapset, otherwise.
Get User Recent Activity
Returns recent activity.
Response format
Get User
This endpoint returns the detail of specified user.
Response format
Returns User object. The following optional attributes on UserCompact are included:
Get Users
Returns list of users.
Response format
Field Type Description users UserCompact[] Includes: country, cover, groups, statistics_rulesets.
Get Wiki Page
The wiki article or image data.
Response Format
Notification Websocket
Connection
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:
Field Type Description event string See below
logout event
Server will disconnect session after sending this event so don’t try to reconnect.
Field Type Description event string logout
new event
New notification. See Notification object for notification types.
Field Type Description event string new data Notification
read event
Notification has been read.
Field Type Description event string read ids number[] id of Notifications which are read
Object Structures
Beatmap
Represent a beatmap. This extends BeatmapCompact with additional attributes.
Field Type Description accuracy float ar float beatmapset_id integer bpm float? convert boolean count_circles integer count_sliders integer count_spinners integer cs float deleted_at Timestamp? drain float hit_length integer is_scoreable boolean last_updated Timestamp mode_int integer passcount integer playcount integer ranked integer See Rank status for list of possible values. url string
BeatmapCompact
Represent a beatmap.
Field Type Description beatmapset_id integer difficulty_rating float id integer mode GameMode status string See Rank status for list of possible values. total_length integer user_id integer version string
Field Type Description beatmapset Beatmapset|BeatmapsetCompact|null Beatmapset for Beatmap object, BeatmapsetCompact for BeatmapCompact object. null if the beatmap doesn’t have associated beatmapset (e.g. deleted). checksum string? failtimes Failtimes max_combo integer
Failtimes
All fields are optional but there’s always at least one field returned.
Field Type Description exit integer[]? Array of length 100. fail integer[]? Array of length 100.
BeatmapDifficultyAttributes
Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.
Field Type max_combo integer star_rating float
Field Type aim_difficulty float approach_rate float flashlight_difficulty float overall_difficulty float slider_factor float speed_difficulty float
taiko
Field Type stamina_difficulty float rhythm_difficulty float colour_difficulty float approach_rate float great_hit_window float
fruits
mania
Field Type great_hit_window float score_multiplier float
BeatmapPlaycount
Represent the playcount of a beatmap.
Field Type Description beatmap_id number beatmap BeatmapCompact? beatmapset BeatmapsetCompact? count number
BeatmapScores
Field Type Description scores Score[] The list of top scores for the beatmap in descending order. userScore BeatmapUserScore? The score of the current user. This is not returned if the current user does not have a score. Note: will be moved to user_score in the future
BeatmapUserScore
Field Type Description position number The position of the score within the requested beatmap ranking. score Score The details of the score.
Beatmapset
Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.
Field Type Description availability.download_disabled boolean availability.more_information string? bpm float can_be_hyped boolean creator string Username of the mapper at the time of beatmapset creation. discussion_locked boolean hype.current integer hype.required integer is_scoreable boolean last_updated Timestamp legacy_thread_url string? nominations.current integer nominations.required integer ranked integer See Rank status for list of possible values. ranked_date Timestamp? source string storyboard boolean submitted_date Timestamp? tags string
The following attributes are always included as well:
Field has_favourited
BeatmapsetCompact
Represents a beatmapset.
Field Type Description artist string artist_unicode string covers Covers creator string favourite_count number id number nsfw boolean play_count number preview_url string source string status string title string title_unicode string user_id number video boolean
Those fields are optional.
Field Type Description beatmaps Beatmap[] converts current_user_attributes description discussions events genre has_favourited boolean language nominations ratings recent_favourites related_users user
Covers
Field Type cover string cover@2x string card string card@2x string list string list@2x string slimcover string slimcover@2x string
Rank status
The possible values are denoted either as integer or string.
Integer String -2 graveyard -1 wip 0 pending 1 ranked 2 approved 3 qualified 4 loved
BeatmapsetDiscussion
Represents a Beatmapset modding discussion.
Field Type Description beatmap BeatmapCompact? beatmap_id number? beatmapset BeatmapsetCompact? beatmapset_id number can_be_resolved boolean can_grant_kudosu boolean created_at Timestamp current_user_attributes CurrentUserAttributes deleted_at Timestamp? deleted_by_id number? id number kudosu_denied boolean last_post_at Timestamp message_type MessageType parent_id number? posts BeatmapsetDiscussionPost[]? resolved boolean starting_post BeatmapsetDiscussionPost? timestamp number? updated_at Timestamp user_id number
MessageType
Name Description hype mapper_note praise problem review suggestion
BeatmapsetDiscussionPost
Field Type Description beatmapset_discussion_id number created_at Timestamp deleted_at Timestamp? deleted_by_id number? id number last_editor_id number? message string system boolean updated_at Timestamp user_id number
BeatmapsetDiscussionVote
Field Type Description beatmapset_discussion_id number created_at Timestamp id number score number updated_at Timestamp user_id number
Build
Field Type created_at Timestamp display_version string id number update_stream UpdateStream? users number version string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes changelog_entries ChangelogEntry[] If the build has no changelog entries, a placeholder is generated. versions Versions
Versions
ChangelogEntry
Field Type category string created_at Timestamp? github_pull_request_id number? github_url string? id number? major boolean repository string? title string? type string url string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes github_user GithubUser If the changelog entry has no GitHub user, a placeholder is generated. message string? Entry message in Markdown format. Embedded HTML is allowed. message_html string? Entry message in HTML format.
ChatChannel
Represents an individual chat «channel» in the game.
Channel Types
Type Permission Check for Joining/Messaging PUBLIC PRIVATE is player in the allowed groups? (channel.allowed_groups) MULTIPLAYER is player currently in the mp game? SPECTATOR TEMPORARY deprecated PM see below (user_channels) GROUP is player in channel? (user_channels)
For PMs, two factors are taken into account:
ChatMessage
Represents an individual Message within a ChatChannel.
Field Type Description message_id number unique identifier for message sender_id number user_id of the sender channel_id number channel_id of where the message was sent timestamp string when the message was sent, ISO-8601 content string message content is_action boolean was this an action? i.e. /me dances sender UserCompact embedded UserCompact object to save additional api lookups
Comment
Represents an single comment.
Field Type Description commentable_id number ID of the object the comment is attached to commentable_type string type of object the comment is attached to created_at string ISO 8601 date deleted_at string? ISO 8601 date if the comment was deleted; null, otherwise edited_at string? ISO 8601 date if the comment was edited; null, otherwise edited_by_id number? user id of the user that edited the post; null, otherwise id number the ID of the comment legacy_name string? username displayed on legacy comments message string? markdown of the comment’s content message_html string? html version of the comment’s content parent_id number? ID of the comment’s parent pinned boolean Pin status of the comment replies_count number number of replies to the comment updated_at string ISO 8601 date user_id number user ID of the poster votes_count number number of votes
CommentBundle
Comments and related data.
Field Type Description commentable_meta CommentableMeta[] ID of the object the comment is attached to comments Comment[] Array of comments ordered according to sort ; cursor Cursor has_more boolean If there are more comments or replies available has_more_id number? included_comments Comment[] Related comments; e.g. parent comments and nested replies pinned_comments Comment[]? Pinned comments sort string one of the CommentSort types top_level_count number? Number of comments at the top level. Not returned for replies. total number? Total number of comments. Not retuned for replies. user_follow boolean is the current user watching the comment thread? user_votes number[] IDs of the comments in the bundle the current user has upvoted users UserCompact[] array of users related to the comments
CommentSort
Type Sort Fields new created_at (descending), id (descending) old created_at (ascending), id (ascending) top votes_count (descending), created_at (descending), id (descending)
Building cursor for comments listing
The returned response will be for comments after the specified sort fields.
For example, use last loaded comment for the fields value to load more comments. Also make sure to use same sort and parent_id values.
CommentableMeta
Metadata of the object that a comment is attached to.
Field Type Description id number the ID of the object title string display title type string the type of the object url string url of the object
CurrentUserAttributes
An object listing various related permissions and states for the current user, related to the object it is attached to.
BeatmapsetDiscussionPermissions
TODO: needs a better name.
Name Description can_destroy Can delete the discussion. can_reopen Can reopen the discussion. can_moderate_kudosu Can allow or deny kudosu. can_resolve Can resolve the discussion. vote_score Current vote given to the discussion.
ChatChannelUserAttributes
Name Type Description can_message boolean Can send messages to this channel. can_message_error string? Reason messages cannot be sent to this channel last_read_id number message_id of last message read.
Cursor
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.
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
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-07-06
2022-06-08
2021-10-28
2021-09-01
2021-08-11
2021-06-14
2021-06-09
2021-04-20
2021-02-25
2020-09-08
2020-08-28
2020-05-01
2020-02-18
2019-10-09
2019-07-18
Endpoint
Base URL
The base URL is: https://osu.ppy.sh/api/[version]/
API Versions
This is combined with the base endpoint to determine where requests should be sent.
Version Status v2 current (not yet public, consider unstable and expect breaking changes) v1 legacy api provided by the old site, will be deprecated soon
Authentication
Routes marked with the OAuth label require a valid OAuth2 token for access.
More information about applications you have registered and granted permissions to can be found here.
The API supports the following grant types:
Before you can use the osu!api, you will need to
Registering an OAuth application
Before you can get an OAuth token, you will need to register an OAuth application on your account settings page
To register an OAuth application you will need to provide the:
Name Description Application Name This is the name that will be visible to users of your application. The name of your application cannot be changed. Application Callback URL The URL in your application where users will be sent after authorization.
The Application Callback URL is required when for using Authorization Codes. This may be left blank if you are only using Client Credentials Grants.
Your new OAuth application will have a Client ID and Client Secret ; the Client Secret is like a password for your OAuth application, it should be kept private and do not share it with anyone else.
Authorization Code Grant
The flow to authorize users for your application is:
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:
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:
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.
Make sure to replace <> 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:
Name Description chat.write Allows sending chat messages on a user’s behalf. delegate Allows acting as the owner of a client; only available for Client Credentials Grant. forum.write Allows creating and editing forum posts on a user’s behalf. friends.read Allows reading of the user’s friend list. identify Allows reading of the public profile of the user ( /me ). public Allows reading of publicly available data on behalf of the user.
identify is the default scope for the Authorization Code Grant and always implicitly provided. The Client Credentials Grant does not currently have any default scopes.
Routes marked with lazer are intended for use by the osu!lazer client and not currently available for use with Authorization Code or Client Credentials grants.
Using the chat.write scope requires either
Managing OAuth applications
Your account settings page will show your registered OAuth applications, and all the OAuth applications you have granted permissions to.
Reset Client Secret
You can generate a new Client Secret by choosing to «Reset client secret», however, this will disable all access tokens issued for the application.
Beatmaps
Lookup Beatmap
Response format
Get a User Beatmap score
Return a User’s score on a Beatmap
Response Format
The position returned depends on the requested mode and mods.
Get a User Beatmap scores
Return a User’s scores on a Beatmap
Response Format
Get Beatmap scores
Returns the top scores for a beatmap
Response Format
Get Beatmap scores (temp)
Returns the top scores for a beatmap from newer client.
This is a temporary endpoint.
Response Format
Get Beatmaps
Returns list of beatmaps.
Response format
Field Type Description beatmaps BeatmapCompact[] Includes: beatmapset (with ratings), failtimes, max_combo.
Get Beatmap
Gets beatmap data for the specified beatmap ID.
Response format
Returns Beatmap object. Following attributes are included in the response object when applicable,
Attribute Notes beatmapset Includes ratings property. failtimes max_combo
Get Beatmap Attributes
Returns difficulty attributes of beatmap with specific mode and mods combination.
Response format
Beatmapset Discussions
Get Beatmapset Discussion Posts
Returns the posts of beatmapset discussions.
Response Format
Get Beatmapset Discussion Votes
Returns the votes given to beatmapset discussions.
Response Format
Get Beatmapset Discussions
Returns a list of beatmapset discussions.
Response Format
Changelog
Get Changelog Build
Returns details of the specified build.
Response Format
Get Changelog Listing
Returns a listing of update streams, builds, and changelog entries.
Response Format
Lookup Changelog Build
Returns details of the specified build.
Response Format
Create New PM
This endpoint allows you to create a new PM channel.
Response Format
Field Type new_channel_id channel_id of newly created ChatChannel presence array of ChatChannel message the sent ChatMessage
This endpoint will only allow the creation of PMs initially, group chat support will come later.
Get Updates
This endpoint returns new messages since the given message_id along with updated channel ‘presence’ data.
Response Format
Get Channel Messages
This endpoint returns the chat messages for a specific channel.
Response Format
Returns an array of ChatMessage
Send Message to Channel
This endpoint returns the chat messages for a specific channel.
Response Format
Join Channel
This endpoint allows you to join a public or multiplayer channel.
Response Format
Returns the joined ChatChannel.
Leave Channel
This endpoint allows you to leave a public channel.
Response Format
Mark Channel as Read
Response Format
Get Channel List
This endpoint returns a list of all joinable public channels.
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.
Response Format
Returns ChatChannel with recent_messages attribute. Note that in the case of PM s, 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.
Response Format
Field Type Description channel ChatChannel users UserCompact Users are only visible for PM channels.
Comments
Get Comments
Returns a list comments and their replies up to 2 levels deep.
Response Format
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.
Response Format
Get a Comment
Gets a comment and its replies up to 2 levels deep.
Response Format
Edit Comment
Edit an existing comment.
Response Format
Delete Comment
Deletes the specified comment.
Response Format
Add Comment vote
Upvotes a comment.
Response Format
Remove Comment vote
Un-upvotes a comment.
Response Format
Forum
Reply Topic
Create a post replying to the specified topic.
Response Format
ForumPost with body included.
Create Topic
Create a new topic.
Response Format
Get Topic and Posts
Get topic and its posts.
Response Format
Edit Topic
Edit topic. Only title can be edited through this endpoint.
Response Format
Edit Post
Edit specified forum post.
Response Format
ForumPost with body included.
Search
Searches users and wiki pages.
Response Format
SearchResult
Multiplayer
Get User High Score
Returns detail of highest score of specified user and the surrounding scores.
Response Format
Get Scores
Returns a list of scores for specified playlist item.
Response Format
Get a Score
Returns detail of specified score and the surrounding scores.
Response Format
Get News Listing
Returns a list of news posts and related metadata.
Response Format
Get News Post
Returns details of the specified news post.
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.
Response Format
Returns an object containing Notification and other related attributes.
Field Type has_more boolean whether or not there are more notifications notifications array of Notification unread_count total unread notifications notification_endpoint url to connect to websocket server
Mark Notifications as Read
This endpoint allows you to mark notifications read.
Response Format
OAuth Tokens
Revoke current token
Revokes currently authenticated token.
Ranking
Get Ranking
Gets the current ranking for the specified type and game mode.
Response Format
Get Spotlights
Gets the list of spotlights.
Response Format
Undocumented
/beatmaps//solo/scores
/beatmaps//solo/scores//beatmapsets/events
/beatmapsets//favourites
/chat/presence
/matches
/matches//rooms//rooms//users//rooms//users//rooms//leaderboard
/rooms//playlist//scores
/rooms//playlist//scores//reports
/rooms
/rooms//seasonal-backgrounds
/scores///download
/scores///beatmapsets/search//beatmapsets/lookup
/beatmapsets//friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
Similar to Get User but with authenticated user (token owner) as user id.
Response format
Additionally, statistics_rulesets is included, containing statistics for all rulesets.
Get User Kudosu
Returns kudosu history.
Response format
Get User Scores
This endpoint returns the scores of specified user.
Response format
Array of Score. Following attributes are included in the response object when applicable.
Get User Beatmaps
Returns the beatmaps of specified user.
Type Notes favourite graveyard loved most_played pending Previously unranked ranked Previously ranked_and_approved
Response format
Array of BeatmapPlaycount when type is most_played ; array of Beatmapset, otherwise.
Get User Recent Activity
Returns recent activity.
Response format
Get User
This endpoint returns the detail of specified user.
Response format
Returns User object. The following optional attributes on UserCompact are included:
Get Users
Returns list of users.
Response format
Field Type Description users UserCompact[] Includes: country, cover, groups, statistics_rulesets.
Get Wiki Page
The wiki article or image data.
Response Format
Notification Websocket
Connection
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:
Field Type Description event string See below
logout event
Server will disconnect session after sending this event so don’t try to reconnect.
Field Type Description event string logout
new event
New notification. See Notification object for notification types.
Field Type Description event string new data Notification
read event
Notification has been read.
Field Type Description event string read ids number[] id of Notifications which are read
Object Structures
Beatmap
Represent a beatmap. This extends BeatmapCompact with additional attributes.
Field Type Description accuracy float ar float beatmapset_id integer bpm float? convert boolean count_circles integer count_sliders integer count_spinners integer cs float deleted_at Timestamp? drain float hit_length integer is_scoreable boolean last_updated Timestamp mode_int integer passcount integer playcount integer ranked integer See Rank status for list of possible values. url string
BeatmapCompact
Represent a beatmap.
Field Type Description beatmapset_id integer difficulty_rating float id integer mode GameMode status string See Rank status for list of possible values. total_length integer user_id integer version string
Field Type Description beatmapset Beatmapset|BeatmapsetCompact|null Beatmapset for Beatmap object, BeatmapsetCompact for BeatmapCompact object. null if the beatmap doesn’t have associated beatmapset (e.g. deleted). checksum string? failtimes Failtimes max_combo integer
Failtimes
All fields are optional but there’s always at least one field returned.
Field Type Description exit integer[]? Array of length 100. fail integer[]? Array of length 100.
BeatmapDifficultyAttributes
Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.
Field Type max_combo integer star_rating float
Field Type aim_difficulty float approach_rate float flashlight_difficulty float overall_difficulty float slider_factor float speed_difficulty float
taiko
Field Type stamina_difficulty float rhythm_difficulty float colour_difficulty float approach_rate float great_hit_window float
fruits
mania
Field Type great_hit_window float score_multiplier float
BeatmapPlaycount
Represent the playcount of a beatmap.
Field Type Description beatmap_id number beatmap BeatmapCompact? beatmapset BeatmapsetCompact? count number
BeatmapScores
Field Type Description scores Score[] The list of top scores for the beatmap in descending order. userScore BeatmapUserScore? The score of the current user. This is not returned if the current user does not have a score. Note: will be moved to user_score in the future
BeatmapUserScore
Field Type Description position number The position of the score within the requested beatmap ranking. score Score The details of the score.
Beatmapset
Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.
Field Type Description availability.download_disabled boolean availability.more_information string? bpm float can_be_hyped boolean creator string Username of the mapper at the time of beatmapset creation. discussion_locked boolean hype.current integer hype.required integer is_scoreable boolean last_updated Timestamp legacy_thread_url string? nominations.current integer nominations.required integer ranked integer See Rank status for list of possible values. ranked_date Timestamp? source string storyboard boolean submitted_date Timestamp? tags string
The following attributes are always included as well:
Field has_favourited
BeatmapsetCompact
Represents a beatmapset.
Field Type Description artist string artist_unicode string covers Covers creator string favourite_count number id number nsfw boolean play_count number preview_url string source string status string title string title_unicode string user_id number video boolean
Those fields are optional.
Field Type Description beatmaps Beatmap[] converts current_user_attributes description discussions events genre has_favourited boolean language nominations ratings recent_favourites related_users user
Covers
Field Type cover string cover@2x string card string card@2x string list string list@2x string slimcover string slimcover@2x string
Rank status
The possible values are denoted either as integer or string.
Integer String -2 graveyard -1 wip 0 pending 1 ranked 2 approved 3 qualified 4 loved
BeatmapsetDiscussion
Represents a Beatmapset modding discussion.
Field Type Description beatmap BeatmapCompact? beatmap_id number? beatmapset BeatmapsetCompact? beatmapset_id number can_be_resolved boolean can_grant_kudosu boolean created_at Timestamp current_user_attributes CurrentUserAttributes deleted_at Timestamp? deleted_by_id number? id number kudosu_denied boolean last_post_at Timestamp message_type MessageType parent_id number? posts BeatmapsetDiscussionPost[]? resolved boolean starting_post BeatmapsetDiscussionPost? timestamp number? updated_at Timestamp user_id number
MessageType
Name Description hype mapper_note praise problem review suggestion
BeatmapsetDiscussionPost
Field Type Description beatmapset_discussion_id number created_at Timestamp deleted_at Timestamp? deleted_by_id number? id number last_editor_id number? message string system boolean updated_at Timestamp user_id number
BeatmapsetDiscussionVote
Field Type Description beatmapset_discussion_id number created_at Timestamp id number score number updated_at Timestamp user_id number
Build
Field Type created_at Timestamp display_version string id number update_stream UpdateStream? users number version string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes changelog_entries ChangelogEntry[] If the build has no changelog entries, a placeholder is generated. versions Versions
Versions
ChangelogEntry
Field Type category string created_at Timestamp? github_pull_request_id number? github_url string? id number? major boolean repository string? title string? type string url string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes github_user GithubUser If the changelog entry has no GitHub user, a placeholder is generated. message string? Entry message in Markdown format. Embedded HTML is allowed. message_html string? Entry message in HTML format.
ChatChannel
Represents an individual chat «channel» in the game.
Channel Types
Type Permission Check for Joining/Messaging PUBLIC PRIVATE is player in the allowed groups? (channel.allowed_groups) MULTIPLAYER is player currently in the mp game? SPECTATOR TEMPORARY deprecated PM see below (user_channels) GROUP is player in channel? (user_channels)
For PMs, two factors are taken into account:
ChatMessage
Represents an individual Message within a ChatChannel.
Field Type Description message_id number unique identifier for message sender_id number user_id of the sender channel_id number channel_id of where the message was sent timestamp string when the message was sent, ISO-8601 content string message content is_action boolean was this an action? i.e. /me dances sender UserCompact embedded UserCompact object to save additional api lookups
Comment
Represents an single comment.
Field Type Description commentable_id number ID of the object the comment is attached to commentable_type string type of object the comment is attached to created_at string ISO 8601 date deleted_at string? ISO 8601 date if the comment was deleted; null, otherwise edited_at string? ISO 8601 date if the comment was edited; null, otherwise edited_by_id number? user id of the user that edited the post; null, otherwise id number the ID of the comment legacy_name string? username displayed on legacy comments message string? markdown of the comment’s content message_html string? html version of the comment’s content parent_id number? ID of the comment’s parent pinned boolean Pin status of the comment replies_count number number of replies to the comment updated_at string ISO 8601 date user_id number user ID of the poster votes_count number number of votes
CommentBundle
Comments and related data.
Field Type Description commentable_meta CommentableMeta[] ID of the object the comment is attached to comments Comment[] Array of comments ordered according to sort ; cursor Cursor has_more boolean If there are more comments or replies available has_more_id number? included_comments Comment[] Related comments; e.g. parent comments and nested replies pinned_comments Comment[]? Pinned comments sort string one of the CommentSort types top_level_count number? Number of comments at the top level. Not returned for replies. total number? Total number of comments. Not retuned for replies. user_follow boolean is the current user watching the comment thread? user_votes number[] IDs of the comments in the bundle the current user has upvoted users UserCompact[] array of users related to the comments
CommentSort
Type Sort Fields new created_at (descending), id (descending) old created_at (ascending), id (ascending) top votes_count (descending), created_at (descending), id (descending)
Building cursor for comments listing
The returned response will be for comments after the specified sort fields.
For example, use last loaded comment for the fields value to load more comments. Also make sure to use same sort and parent_id values.
CommentableMeta
Metadata of the object that a comment is attached to.
Field Type Description id number the ID of the object title string display title type string the type of the object url string url of the object
CurrentUserAttributes
An object listing various related permissions and states for the current user, related to the object it is attached to.
BeatmapsetDiscussionPermissions
TODO: needs a better name.
Name Description can_destroy Can delete the discussion. can_reopen Can reopen the discussion. can_moderate_kudosu Can allow or deny kudosu. can_resolve Can resolve the discussion. vote_score Current vote given to the discussion.
ChatChannelUserAttributes
Name Type Description can_message boolean Can send messages to this channel. can_message_error string? Reason messages cannot be sent to this channel last_read_id number message_id of last message read.
Cursor
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.
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
osu!api open beta
Нет аккаунта?
osu!api open beta
I’ve had an API available for a while but until now it has been on a private on-request basis. In order to try and make developing third party services which expand and support osu!, I have added an API key setup and started to document the API.
Documentation will be expanded as I find time to do so! If anyone currently using the API is able to help expand the documentation then please do.
comentarinformal wrote:
Before I spam it with requests that might not exist, is there anything to get user’s information?
(Also, is there anything to login users from this page in other places?)
There is /api/get_user
Gonna write an entry with the information I have about it.
Is there a fair use limit? (e.g. no more than XX requests per day)
For get_user, I suppose there is a mode parameter for getting user information for Taiko, CtB and osu!mania? Or do I have to file an issue in GitHub? Nevermind, I found it, the parameter to add is called «m» I have edited the GitHub wiki.
Oh well. I have some questions:
Are only the beatmap and user endpoints available?
The parameter «since» in /get_beatmap how I need to pass the time on it? UTC or unix timestamp?
Do I need to pass the key on the wiki’s API too?
Edit: What the countX values mean? Number of beatmaps?
comentarinformal wrote:
Before I spam it with requests that might not exist, is there anything to get user’s information?
(Also, is there anything to login users from this page in other places?)
I guess I’ll update my userbar too when I find some time.
Damnae wrote:
I guess I’ll update my userbar too when I find some time.
I registered it for osu!userbar, but I also use it for my «Big ugly white signature», they are not on the same webserver, but it works fine
I belive only you and peppy can see the name you used, too.
(Yes I took my lazyness off, it was not that long to update ^^)
@Repflez: I tried using your API-powered signature and I get something weird.
Since I only aim for SS, I have 100% Accuracy all the time, and the Accuracy display is weird.
(I now know that despite having all-SS records, the note hit count for getting 50s and 100s are still counted all the time )
Winshley wrote:
@Repflez: I tried using your API-powered signature and I get something weird.
Since I only aim for SS, I have 100% Accuracy all the time, and the Accuracy display is weird.
(I now know that despite having all-SS records, the note hit count for getting 50s and 100s are still counted all the time )
So that’s what the CountX values mean. Thanks for that. I already went and changed the accuracy to show a centered «100% Accuracy» if it’s 100. Forget that. I ditched the bar on it and used the extra space for showing the PP.
(I love how the 300 count ended overlaping the border)
Repflez wrote:
So that’s what the CountX values mean. Thanks for that.
Yeah. At first I thought that there was something wrong with the API showing 50s and 100s despite having 100% Accuracy, until I actually calculated all 300s + 100s + 50s = «Total Hits» on our profile.
About the 300 overlap though, it does need some fix:
When you reached 10 millions of 300 hits, the last number is cut off. Cookiezi has 17 millions of 300 hits.
I’m not sure how the level bar breaking happens though. I was thinking that it probably because I don’t have any ranked score on osu!mania?
[Archived] getting osu! api token
Нет аккаунта?
[Archived] getting osu! api token
here is the website I am currently using this for https://osu-api-crap.minecreeper0913.repl.co
well since the project I am using is all python and not javascript I am using a new tab browser to just test it and so far the code I am using is
url = («https://osu.ppy.sh/oauth/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=%s» % (code))
the &code=%s is basically just grabbing the code that has been given back by oauth and using that as the url, when I am testing it though I am actually using my code
Never share your client secret, it’s secret for a reason. I would recommend resetting it ASAP.
Are you just typing that URL into your browser or are you actually sending it as a post request with whatever python code you have? Typing the URL into your browser won’t work.
The token endpoint takes the parameters in the body of the request, not as query parameters. You are also missing some parameters, like redirect_uri and grant_type.
If you are using python’s requests library, you can do something like this:
Might have some syntax errors because I wrote that from memory and didn’t check anything in an IDE or by running it.
You can try without specifying the content type in your headers, it might work without it. Very simply, the content type header describes what type of content or data is being sent. As far as I recall, the server is expecting that content type but I could be wrong.
now starting to realize that I might have done this a bit wrong, this is the first time I have used an API for something so everything I am doing is new to me.
So the first thing that is happening is that you press the login to link your osu API to the website, then it grabs your code and redirects you to the home website with the code in the url for example http://www.website.com/code=j9838r9y82g9438gh8243hg384hg, and it is supposed to use that, but when in testing it just returns favicon.ico, and I don’t know what that is or means so I might have to change my get request, another issue is but how would I make it get that auth code?
I don’t know anything about the project you are working on, so unfortunately I don’t think I can really answer any of the questions you’re asking.
I don’t know what you mean by a favicon being returned and I also don’t know what you are using the handle the backend of your site, so I can’t specifically tell you how to grab the code. Whatever you are using should have some way of getting query parameters from the URL.
Oauth2 is a very standardized and should be nearly the same everywhere that uses it. osu! is no exception. I would highly recommend looking up and reading about the authorization code flow that you are trying to use here. There should be a ton of resources and maybe a few code examples as well.
There might not be any videos specific to osu!’s API, but there are definitely Oauth2 tutorial videos and examples out there in probably every programming language, which is what you are dealing with right now.
For example, here is a video I found after a quick Google search that is using Python. I can’t fully comment on its quality since I just skimmed through it, but the general flow that the creator of the video goes over seems like it will at least cover how OAuth2 works in general, even if it’s not in the context of osu!’s API.
And even if you don’t really like reading, there are still some pretty good resources you can use that might help in addition to watching a video. Like this and this for example. Again, I’ve only skimmed through these, but they also seem to be pretty good.
here is the code I use:
NOTE I did not actually use SECRET as the secret I have it as SECRET because its secret
/beatmapsets/search//beatmapsets/lookup
/beatmapsets//friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
/friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
Similar to Get User but with authenticated user (token owner) as user id.
Response format
Additionally, statistics_rulesets is included, containing statistics for all rulesets.
Get User Kudosu
Returns kudosu history.
Response format
Get User Scores
This endpoint returns the scores of specified user.
Response format
Array of Score. Following attributes are included in the response object when applicable.
Get User Beatmaps
Returns the beatmaps of specified user.
| Type | Notes |
|---|---|
| favourite | |
| graveyard | |
| loved | |
| most_played | |
| pending | Previously unranked |
| ranked | Previously ranked_and_approved |
Response format
Array of BeatmapPlaycount when type is most_played ; array of Beatmapset, otherwise.
Get User Recent Activity
Returns recent activity.
Response format
Get User
This endpoint returns the detail of specified user.
Response format
Returns User object. The following optional attributes on UserCompact are included:
Get Users
Returns list of users.
Response format
| Field | Type | Description |
|---|---|---|
| users | UserCompact[] | Includes: country, cover, groups, statistics_rulesets. |
Get Wiki Page
The wiki article or image data.
Response Format
Notification Websocket
Connection
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:
| Field | Type | Description |
|---|---|---|
| event | string | See below |
logout event
Server will disconnect session after sending this event so don’t try to reconnect.
| Field | Type | Description |
|---|---|---|
| event | string | logout |
new event
New notification. See Notification object for notification types.
| Field | Type | Description |
|---|---|---|
| event | string | new |
| data | Notification |
read event
Notification has been read.
| Field | Type | Description |
|---|---|---|
| event | string | read |
| ids | number[] | id of Notifications which are read |
Object Structures
Beatmap
Represent a beatmap. This extends BeatmapCompact with additional attributes.
| Field | Type | Description |
|---|---|---|
| accuracy | float | |
| ar | float | |
| beatmapset_id | integer | |
| bpm | float? | |
| convert | boolean | |
| count_circles | integer | |
| count_sliders | integer | |
| count_spinners | integer | |
| cs | float | |
| deleted_at | Timestamp? | |
| drain | float | |
| hit_length | integer | |
| is_scoreable | boolean | |
| last_updated | Timestamp | |
| mode_int | integer | |
| passcount | integer | |
| playcount | integer | |
| ranked | integer | See Rank status for list of possible values. |
| url | string |
BeatmapCompact
Represent a beatmap.
| Field | Type | Description |
|---|---|---|
| beatmapset_id | integer | |
| difficulty_rating | float | |
| id | integer | |
| mode | GameMode | |
| status | string | See Rank status for list of possible values. |
| total_length | integer | |
| user_id | integer | |
| version | string |
| Field | Type | Description |
|---|---|---|
| beatmapset | Beatmapset|BeatmapsetCompact|null | Beatmapset for Beatmap object, BeatmapsetCompact for BeatmapCompact object. null if the beatmap doesn’t have associated beatmapset (e.g. deleted). |
| checksum | string? | |
| failtimes | Failtimes | |
| max_combo | integer |
Failtimes
All fields are optional but there’s always at least one field returned.
| Field | Type | Description |
|---|---|---|
| exit | integer[]? | Array of length 100. |
| fail | integer[]? | Array of length 100. |
BeatmapDifficultyAttributes
Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.
| Field | Type |
|---|---|
| max_combo | integer |
| star_rating | float |
| Field | Type |
|---|---|
| aim_difficulty | float |
| approach_rate | float |
| flashlight_difficulty | float |
| overall_difficulty | float |
| slider_factor | float |
| speed_difficulty | float |
taiko
| Field | Type |
|---|---|
| stamina_difficulty | float |
| rhythm_difficulty | float |
| colour_difficulty | float |
| approach_rate | float |
| great_hit_window | float |
fruits
mania
| Field | Type |
|---|---|
| great_hit_window | float |
| score_multiplier | float |
BeatmapPlaycount
Represent the playcount of a beatmap.
| Field | Type | Description |
|---|---|---|
| beatmap_id | number | |
| beatmap | BeatmapCompact? | |
| beatmapset | BeatmapsetCompact? | |
| count | number |
BeatmapScores
| Field | Type | Description |
|---|---|---|
| scores | Score[] | The list of top scores for the beatmap in descending order. |
| userScore | BeatmapUserScore? | The score of the current user. This is not returned if the current user does not have a score. Note: will be moved to user_score in the future |
BeatmapUserScore
| Field | Type | Description |
|---|---|---|
| position | number | The position of the score within the requested beatmap ranking. |
| score | Score | The details of the score. |
Beatmapset
Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.
| Field | Type | Description |
|---|---|---|
| availability.download_disabled | boolean | |
| availability.more_information | string? | |
| bpm | float | |
| can_be_hyped | boolean | |
| creator | string | Username of the mapper at the time of beatmapset creation. |
| discussion_locked | boolean | |
| hype.current | integer | |
| hype.required | integer | |
| is_scoreable | boolean | |
| last_updated | Timestamp | |
| legacy_thread_url | string? | |
| nominations.current | integer | |
| nominations.required | integer | |
| ranked | integer | See Rank status for list of possible values. |
| ranked_date | Timestamp? | |
| source | string | |
| storyboard | boolean | |
| submitted_date | Timestamp? | |
| tags | string |
The following attributes are always included as well:
| Field |
|---|
| has_favourited |
BeatmapsetCompact
Represents a beatmapset.
| Field | Type | Description |
|---|---|---|
| artist | string | |
| artist_unicode | string | |
| covers | Covers | |
| creator | string | |
| favourite_count | number | |
| id | number | |
| nsfw | boolean | |
| play_count | number | |
| preview_url | string | |
| source | string | |
| status | string | |
| title | string | |
| title_unicode | string | |
| user_id | number | |
| video | boolean |
Those fields are optional.
| Field | Type | Description |
|---|---|---|
| beatmaps | Beatmap[] | |
| converts | ||
| current_user_attributes | ||
| description | ||
| discussions | ||
| events | ||
| genre | ||
| has_favourited | boolean | |
| language | ||
| nominations | ||
| ratings | ||
| recent_favourites | ||
| related_users | ||
| user |
Covers
| Field | Type |
|---|---|
| cover | string |
| cover@2x | string |
| card | string |
| card@2x | string |
| list | string |
| list@2x | string |
| slimcover | string |
| slimcover@2x | string |
Rank status
The possible values are denoted either as integer or string.
| Integer | String |
|---|---|
| -2 | graveyard |
| -1 | wip |
| 0 | pending |
| 1 | ranked |
| 2 | approved |
| 3 | qualified |
| 4 | loved |
BeatmapsetDiscussion
Represents a Beatmapset modding discussion.
| Field | Type | Description |
|---|---|---|
| beatmap | BeatmapCompact? | |
| beatmap_id | number? | |
| beatmapset | BeatmapsetCompact? | |
| beatmapset_id | number | |
| can_be_resolved | boolean | |
| can_grant_kudosu | boolean | |
| created_at | Timestamp | |
| current_user_attributes | CurrentUserAttributes | |
| deleted_at | Timestamp? | |
| deleted_by_id | number? | |
| id | number | |
| kudosu_denied | boolean | |
| last_post_at | Timestamp | |
| message_type | MessageType | |
| parent_id | number? | |
| posts | BeatmapsetDiscussionPost[]? | |
| resolved | boolean | |
| starting_post | BeatmapsetDiscussionPost? | |
| timestamp | number? | |
| updated_at | Timestamp | |
| user_id | number |
MessageType
| Name | Description |
|---|---|
| hype | |
| mapper_note | |
| praise | |
| problem | |
| review | |
| suggestion |
BeatmapsetDiscussionPost
| Field | Type | Description |
|---|---|---|
| beatmapset_discussion_id | number | |
| created_at | Timestamp | |
| deleted_at | Timestamp? | |
| deleted_by_id | number? | |
| id | number | |
| last_editor_id | number? | |
| message | string | |
| system | boolean | |
| updated_at | Timestamp | |
| user_id | number |
BeatmapsetDiscussionVote
| Field | Type | Description |
|---|---|---|
| beatmapset_discussion_id | number | |
| created_at | Timestamp | |
| id | number | |
| score | number | |
| updated_at | Timestamp | |
| user_id | number |
Build
| Field | Type |
|---|---|
| created_at | Timestamp |
| display_version | string |
| id | number |
| update_stream | UpdateStream? |
| users | number |
| version | string? |
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
| Field | Type | Notes |
|---|---|---|
| changelog_entries | ChangelogEntry[] | If the build has no changelog entries, a placeholder is generated. |
| versions | Versions |
Versions
ChangelogEntry
| Field | Type |
|---|---|
| category | string |
| created_at | Timestamp? |
| github_pull_request_id | number? |
| github_url | string? |
| id | number? |
| major | boolean |
| repository | string? |
| title | string? |
| type | string |
| url | string? |
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
| Field | Type | Notes |
|---|---|---|
| github_user | GithubUser | If the changelog entry has no GitHub user, a placeholder is generated. |
| message | string? | Entry message in Markdown format. Embedded HTML is allowed. |
| message_html | string? | Entry message in HTML format. |
ChatChannel
Represents an individual chat «channel» in the game.
Channel Types
| Type | Permission Check for Joining/Messaging |
|---|---|
| PUBLIC | |
| PRIVATE | is player in the allowed groups? (channel.allowed_groups) |
| MULTIPLAYER | is player currently in the mp game? |
| SPECTATOR | |
| TEMPORARY | deprecated |
| PM | see below (user_channels) |
| GROUP | is player in channel? (user_channels) |
For PMs, two factors are taken into account:
ChatMessage
Represents an individual Message within a ChatChannel.
| Field | Type | Description |
|---|---|---|
| message_id | number | unique identifier for message |
| sender_id | number | user_id of the sender |
| channel_id | number | channel_id of where the message was sent |
| timestamp | string | when the message was sent, ISO-8601 |
| content | string | message content |
| is_action | boolean | was this an action? i.e. /me dances |
| sender | UserCompact | embedded UserCompact object to save additional api lookups |
Comment
Represents an single comment.
| Field | Type | Description |
|---|---|---|
| commentable_id | number | ID of the object the comment is attached to |
| commentable_type | string | type of object the comment is attached to |
| created_at | string | ISO 8601 date |
| deleted_at | string? | ISO 8601 date if the comment was deleted; null, otherwise |
| edited_at | string? | ISO 8601 date if the comment was edited; null, otherwise |
| edited_by_id | number? | user id of the user that edited the post; null, otherwise |
| id | number | the ID of the comment |
| legacy_name | string? | username displayed on legacy comments |
| message | string? | markdown of the comment’s content |
| message_html | string? | html version of the comment’s content |
| parent_id | number? | ID of the comment’s parent |
| pinned | boolean | Pin status of the comment |
| replies_count | number | number of replies to the comment |
| updated_at | string | ISO 8601 date |
| user_id | number | user ID of the poster |
| votes_count | number | number of votes |
CommentBundle
Comments and related data.
| Field | Type | Description |
|---|---|---|
| commentable_meta | CommentableMeta[] | ID of the object the comment is attached to |
| comments | Comment[] | Array of comments ordered according to sort ; |
| cursor | Cursor | |
| has_more | boolean | If there are more comments or replies available |
| has_more_id | number? | |
| included_comments | Comment[] | Related comments; e.g. parent comments and nested replies |
| pinned_comments | Comment[]? | Pinned comments |
| sort | string | one of the CommentSort types |
| top_level_count | number? | Number of comments at the top level. Not returned for replies. |
| total | number? | Total number of comments. Not retuned for replies. |
| user_follow | boolean | is the current user watching the comment thread? |
| user_votes | number[] | IDs of the comments in the bundle the current user has upvoted |
| users | UserCompact[] | array of users related to the comments |
CommentSort
| Type | Sort Fields |
|---|---|
| new | created_at (descending), id (descending) |
| old | created_at (ascending), id (ascending) |
| top | votes_count (descending), created_at (descending), id (descending) |
Building cursor for comments listing
The returned response will be for comments after the specified sort fields.
For example, use last loaded comment for the fields value to load more comments. Also make sure to use same sort and parent_id values.
CommentableMeta
Metadata of the object that a comment is attached to.
| Field | Type | Description |
|---|---|---|
| id | number | the ID of the object |
| title | string | display title |
| type | string | the type of the object |
| url | string | url of the object |
CurrentUserAttributes
An object listing various related permissions and states for the current user, related to the object it is attached to.
BeatmapsetDiscussionPermissions
TODO: needs a better name.
| Name | Description |
|---|---|
| can_destroy | Can delete the discussion. |
| can_reopen | Can reopen the discussion. |
| can_moderate_kudosu | Can allow or deny kudosu. |
| can_resolve | Can resolve the discussion. |
| vote_score | Current vote given to the discussion. |
ChatChannelUserAttributes
| Name | Type | Description |
|---|---|---|
| can_message | boolean | Can send messages to this channel. |
| can_message_error | string? | Reason messages cannot be sent to this channel |
| last_read_id | number | message_id of last message read. |
Cursor
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.
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
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-07-06
2022-06-08
2021-10-28
2021-09-01
2021-08-11
2021-06-14
2021-06-09
2021-04-20
2021-02-25
2020-09-08
2020-08-28
2020-05-01
2020-02-18
2019-10-09
2019-07-18
Endpoint
Base URL
The base URL is: https://osu.ppy.sh/api/[version]/
API Versions
This is combined with the base endpoint to determine where requests should be sent.
| Version | Status |
|---|---|
| v2 | current (not yet public, consider unstable and expect breaking changes) |
| v1 | legacy api provided by the old site, will be deprecated soon |
Authentication
Routes marked with the OAuth label require a valid OAuth2 token for access.
More information about applications you have registered and granted permissions to can be found here.
The API supports the following grant types:
Before you can use the osu!api, you will need to
Registering an OAuth application
Before you can get an OAuth token, you will need to register an OAuth application on your account settings page
To register an OAuth application you will need to provide the:
| Name | Description |
|---|---|
| Application Name | This is the name that will be visible to users of your application. The name of your application cannot be changed. |
| Application Callback URL | The URL in your application where users will be sent after authorization. |
The Application Callback URL is required when for using Authorization Codes. This may be left blank if you are only using Client Credentials Grants.
Your new OAuth application will have a Client ID and Client Secret ; the Client Secret is like a password for your OAuth application, it should be kept private and do not share it with anyone else.
Authorization Code Grant
The flow to authorize users for your application is:
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:
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:
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.
Make sure to replace <
> 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:
| Name | Description |
|---|---|
| chat.write | Allows sending chat messages on a user’s behalf. |
| delegate | Allows acting as the owner of a client; only available for Client Credentials Grant. |
| forum.write | Allows creating and editing forum posts on a user’s behalf. |
| friends.read | Allows reading of the user’s friend list. |
| identify | Allows reading of the public profile of the user ( /me ). |
| public | Allows reading of publicly available data on behalf of the user. |
identify is the default scope for the Authorization Code Grant and always implicitly provided. The Client Credentials Grant does not currently have any default scopes.
Routes marked with lazer are intended for use by the osu!lazer client and not currently available for use with Authorization Code or Client Credentials grants.
Using the chat.write scope requires either
Managing OAuth applications
Your account settings page will show your registered OAuth applications, and all the OAuth applications you have granted permissions to.
Reset Client Secret
You can generate a new Client Secret by choosing to «Reset client secret», however, this will disable all access tokens issued for the application.
Beatmaps
Lookup Beatmap
Response format
Get a User Beatmap score
Return a User’s score on a Beatmap
Response Format
The position returned depends on the requested mode and mods.
Get a User Beatmap scores
Return a User’s scores on a Beatmap
Response Format
Get Beatmap scores
Returns the top scores for a beatmap
Response Format
Get Beatmap scores (temp)
Returns the top scores for a beatmap from newer client.
This is a temporary endpoint.
Response Format
Get Beatmaps
Returns list of beatmaps.
Response format
| Field | Type | Description |
|---|---|---|
| beatmaps | BeatmapCompact[] | Includes: beatmapset (with ratings), failtimes, max_combo. |
Get Beatmap
Gets beatmap data for the specified beatmap ID.
Response format
Returns Beatmap object. Following attributes are included in the response object when applicable,
| Attribute | Notes |
|---|---|
| beatmapset | Includes ratings property. |
| failtimes | |
| max_combo |
Get Beatmap Attributes
Returns difficulty attributes of beatmap with specific mode and mods combination.
Response format
Beatmapset Discussions
Get Beatmapset Discussion Posts
Returns the posts of beatmapset discussions.
Response Format
Get Beatmapset Discussion Votes
Returns the votes given to beatmapset discussions.
Response Format
Get Beatmapset Discussions
Returns a list of beatmapset discussions.
Response Format
Changelog
Get Changelog Build
Returns details of the specified build.
Response Format
Get Changelog Listing
Returns a listing of update streams, builds, and changelog entries.
Response Format
Lookup Changelog Build
Returns details of the specified build.
Response Format
Create New PM
This endpoint allows you to create a new PM channel.
Response Format
| Field | Type |
|---|---|
| new_channel_id | channel_id of newly created ChatChannel |
| presence | array of ChatChannel |
| message | the sent ChatMessage |
This endpoint will only allow the creation of PMs initially, group chat support will come later.
Get Updates
This endpoint returns new messages since the given message_id along with updated channel ‘presence’ data.
Response Format
Get Channel Messages
This endpoint returns the chat messages for a specific channel.
Response Format
Returns an array of ChatMessage
Send Message to Channel
This endpoint returns the chat messages for a specific channel.
Response Format
Join Channel
This endpoint allows you to join a public or multiplayer channel.
Response Format
Returns the joined ChatChannel.
Leave Channel
This endpoint allows you to leave a public channel.
Response Format
Mark Channel as Read
Response Format
Get Channel List
This endpoint returns a list of all joinable public channels.
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.
Response Format
Returns ChatChannel with recent_messages attribute. Note that in the case of PM s, 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.
Response Format
| Field | Type | Description |
|---|---|---|
| channel | ChatChannel | |
| users | UserCompact | Users are only visible for PM channels. |
Comments
Get Comments
Returns a list comments and their replies up to 2 levels deep.
Response Format
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.
Response Format
Get a Comment
Gets a comment and its replies up to 2 levels deep.
Response Format
Edit Comment
Edit an existing comment.
Response Format
Delete Comment
Deletes the specified comment.
Response Format
Add Comment vote
Upvotes a comment.
Response Format
Remove Comment vote
Un-upvotes a comment.
Response Format
Forum
Reply Topic
Create a post replying to the specified topic.
Response Format
ForumPost with body included.
Create Topic
Create a new topic.
Response Format
Get Topic and Posts
Get topic and its posts.
Response Format
Edit Topic
Edit topic. Only title can be edited through this endpoint.
Response Format
Edit Post
Edit specified forum post.
Response Format
ForumPost with body included.
Search
Searches users and wiki pages.
Response Format
SearchResult
Multiplayer
Get User High Score
Returns detail of highest score of specified user and the surrounding scores.
Response Format
Get Scores
Returns a list of scores for specified playlist item.
Response Format
Get a Score
Returns detail of specified score and the surrounding scores.
Response Format
Get News Listing
Returns a list of news posts and related metadata.
Response Format
Get News Post
Returns details of the specified news post.
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.
Response Format
Returns an object containing Notification and other related attributes.
| Field | Type |
|---|---|
| has_more | boolean whether or not there are more notifications |
| notifications | array of Notification |
| unread_count | total unread notifications |
| notification_endpoint | url to connect to websocket server |
Mark Notifications as Read
This endpoint allows you to mark notifications read.
Response Format
OAuth Tokens
Revoke current token
Revokes currently authenticated token.
Ranking
Get Ranking
Gets the current ranking for the specified type and game mode.
Response Format
Get Spotlights
Gets the list of spotlights.
Response Format
Undocumented
/beatmaps//solo/scores
/beatmaps//solo/scores//beatmapsets/events
/beatmapsets//favourites
/chat/presence
/matches
/matches//rooms//rooms//users//rooms//users//rooms//leaderboard
/rooms//playlist//scores
/rooms//playlist//scores//reports
/rooms
/rooms//seasonal-backgrounds
/scores///download
/scores///beatmapsets/search//beatmapsets/lookup
/beatmapsets//friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
Similar to Get User but with authenticated user (token owner) as user id.
Response format
Additionally, statistics_rulesets is included, containing statistics for all rulesets.
Get User Kudosu
Returns kudosu history.
Response format
Get User Scores
This endpoint returns the scores of specified user.
Response format
Array of Score. Following attributes are included in the response object when applicable.
Get User Beatmaps
Returns the beatmaps of specified user.
Type Notes favourite graveyard loved most_played pending Previously unranked ranked Previously ranked_and_approved
Response format
Array of BeatmapPlaycount when type is most_played ; array of Beatmapset, otherwise.
Get User Recent Activity
Returns recent activity.
Response format
Get User
This endpoint returns the detail of specified user.
Response format
Returns User object. The following optional attributes on UserCompact are included:
Get Users
Returns list of users.
Response format
Field Type Description users UserCompact[] Includes: country, cover, groups, statistics_rulesets.
Get Wiki Page
The wiki article or image data.
Response Format
Notification Websocket
Connection
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:
Field Type Description event string See below
logout event
Server will disconnect session after sending this event so don’t try to reconnect.
Field Type Description event string logout
new event
New notification. See Notification object for notification types.
Field Type Description event string new data Notification
read event
Notification has been read.
Field Type Description event string read ids number[] id of Notifications which are read
Object Structures
Beatmap
Represent a beatmap. This extends BeatmapCompact with additional attributes.
Field Type Description accuracy float ar float beatmapset_id integer bpm float? convert boolean count_circles integer count_sliders integer count_spinners integer cs float deleted_at Timestamp? drain float hit_length integer is_scoreable boolean last_updated Timestamp mode_int integer passcount integer playcount integer ranked integer See Rank status for list of possible values. url string
BeatmapCompact
Represent a beatmap.
Field Type Description beatmapset_id integer difficulty_rating float id integer mode GameMode status string See Rank status for list of possible values. total_length integer user_id integer version string
Field Type Description beatmapset Beatmapset|BeatmapsetCompact|null Beatmapset for Beatmap object, BeatmapsetCompact for BeatmapCompact object. null if the beatmap doesn’t have associated beatmapset (e.g. deleted). checksum string? failtimes Failtimes max_combo integer
Failtimes
All fields are optional but there’s always at least one field returned.
Field Type Description exit integer[]? Array of length 100. fail integer[]? Array of length 100.
BeatmapDifficultyAttributes
Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.
Field Type max_combo integer star_rating float
Field Type aim_difficulty float approach_rate float flashlight_difficulty float overall_difficulty float slider_factor float speed_difficulty float
taiko
Field Type stamina_difficulty float rhythm_difficulty float colour_difficulty float approach_rate float great_hit_window float
fruits
mania
Field Type great_hit_window float score_multiplier float
BeatmapPlaycount
Represent the playcount of a beatmap.
Field Type Description beatmap_id number beatmap BeatmapCompact? beatmapset BeatmapsetCompact? count number
BeatmapScores
Field Type Description scores Score[] The list of top scores for the beatmap in descending order. userScore BeatmapUserScore? The score of the current user. This is not returned if the current user does not have a score. Note: will be moved to user_score in the future
BeatmapUserScore
Field Type Description position number The position of the score within the requested beatmap ranking. score Score The details of the score.
Beatmapset
Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.
Field Type Description availability.download_disabled boolean availability.more_information string? bpm float can_be_hyped boolean creator string Username of the mapper at the time of beatmapset creation. discussion_locked boolean hype.current integer hype.required integer is_scoreable boolean last_updated Timestamp legacy_thread_url string? nominations.current integer nominations.required integer ranked integer See Rank status for list of possible values. ranked_date Timestamp? source string storyboard boolean submitted_date Timestamp? tags string
The following attributes are always included as well:
Field has_favourited
BeatmapsetCompact
Represents a beatmapset.
Field Type Description artist string artist_unicode string covers Covers creator string favourite_count number id number nsfw boolean play_count number preview_url string source string status string title string title_unicode string user_id number video boolean
Those fields are optional.
Field Type Description beatmaps Beatmap[] converts current_user_attributes description discussions events genre has_favourited boolean language nominations ratings recent_favourites related_users user
Covers
Field Type cover string cover@2x string card string card@2x string list string list@2x string slimcover string slimcover@2x string
Rank status
The possible values are denoted either as integer or string.
Integer String -2 graveyard -1 wip 0 pending 1 ranked 2 approved 3 qualified 4 loved
BeatmapsetDiscussion
Represents a Beatmapset modding discussion.
Field Type Description beatmap BeatmapCompact? beatmap_id number? beatmapset BeatmapsetCompact? beatmapset_id number can_be_resolved boolean can_grant_kudosu boolean created_at Timestamp current_user_attributes CurrentUserAttributes deleted_at Timestamp? deleted_by_id number? id number kudosu_denied boolean last_post_at Timestamp message_type MessageType parent_id number? posts BeatmapsetDiscussionPost[]? resolved boolean starting_post BeatmapsetDiscussionPost? timestamp number? updated_at Timestamp user_id number
MessageType
Name Description hype mapper_note praise problem review suggestion
BeatmapsetDiscussionPost
Field Type Description beatmapset_discussion_id number created_at Timestamp deleted_at Timestamp? deleted_by_id number? id number last_editor_id number? message string system boolean updated_at Timestamp user_id number
BeatmapsetDiscussionVote
Field Type Description beatmapset_discussion_id number created_at Timestamp id number score number updated_at Timestamp user_id number
Build
Field Type created_at Timestamp display_version string id number update_stream UpdateStream? users number version string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes changelog_entries ChangelogEntry[] If the build has no changelog entries, a placeholder is generated. versions Versions
Versions
ChangelogEntry
Field Type category string created_at Timestamp? github_pull_request_id number? github_url string? id number? major boolean repository string? title string? type string url string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes github_user GithubUser If the changelog entry has no GitHub user, a placeholder is generated. message string? Entry message in Markdown format. Embedded HTML is allowed. message_html string? Entry message in HTML format.
ChatChannel
Represents an individual chat «channel» in the game.
Channel Types
Type Permission Check for Joining/Messaging PUBLIC PRIVATE is player in the allowed groups? (channel.allowed_groups) MULTIPLAYER is player currently in the mp game? SPECTATOR TEMPORARY deprecated PM see below (user_channels) GROUP is player in channel? (user_channels)
For PMs, two factors are taken into account:
ChatMessage
Represents an individual Message within a ChatChannel.
Field Type Description message_id number unique identifier for message sender_id number user_id of the sender channel_id number channel_id of where the message was sent timestamp string when the message was sent, ISO-8601 content string message content is_action boolean was this an action? i.e. /me dances sender UserCompact embedded UserCompact object to save additional api lookups
Comment
Represents an single comment.
Field Type Description commentable_id number ID of the object the comment is attached to commentable_type string type of object the comment is attached to created_at string ISO 8601 date deleted_at string? ISO 8601 date if the comment was deleted; null, otherwise edited_at string? ISO 8601 date if the comment was edited; null, otherwise edited_by_id number? user id of the user that edited the post; null, otherwise id number the ID of the comment legacy_name string? username displayed on legacy comments message string? markdown of the comment’s content message_html string? html version of the comment’s content parent_id number? ID of the comment’s parent pinned boolean Pin status of the comment replies_count number number of replies to the comment updated_at string ISO 8601 date user_id number user ID of the poster votes_count number number of votes
CommentBundle
Comments and related data.
Field Type Description commentable_meta CommentableMeta[] ID of the object the comment is attached to comments Comment[] Array of comments ordered according to sort ; cursor Cursor has_more boolean If there are more comments or replies available has_more_id number? included_comments Comment[] Related comments; e.g. parent comments and nested replies pinned_comments Comment[]? Pinned comments sort string one of the CommentSort types top_level_count number? Number of comments at the top level. Not returned for replies. total number? Total number of comments. Not retuned for replies. user_follow boolean is the current user watching the comment thread? user_votes number[] IDs of the comments in the bundle the current user has upvoted users UserCompact[] array of users related to the comments
CommentSort
Type Sort Fields new created_at (descending), id (descending) old created_at (ascending), id (ascending) top votes_count (descending), created_at (descending), id (descending)
Building cursor for comments listing
The returned response will be for comments after the specified sort fields.
For example, use last loaded comment for the fields value to load more comments. Also make sure to use same sort and parent_id values.
CommentableMeta
Metadata of the object that a comment is attached to.
Field Type Description id number the ID of the object title string display title type string the type of the object url string url of the object
CurrentUserAttributes
An object listing various related permissions and states for the current user, related to the object it is attached to.
BeatmapsetDiscussionPermissions
TODO: needs a better name.
Name Description can_destroy Can delete the discussion. can_reopen Can reopen the discussion. can_moderate_kudosu Can allow or deny kudosu. can_resolve Can resolve the discussion. vote_score Current vote given to the discussion.
ChatChannelUserAttributes
Name Type Description can_message boolean Can send messages to this channel. can_message_error string? Reason messages cannot be sent to this channel last_read_id number message_id of last message read.
Cursor
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.
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
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-07-06
2022-06-08
2021-10-28
2021-09-01
2021-08-11
2021-06-14
2021-06-09
2021-04-20
2021-02-25
2020-09-08
2020-08-28
2020-05-01
2020-02-18
2019-10-09
2019-07-18
Endpoint
Base URL
The base URL is: https://osu.ppy.sh/api/[version]/
API Versions
This is combined with the base endpoint to determine where requests should be sent.
Version Status v2 current (not yet public, consider unstable and expect breaking changes) v1 legacy api provided by the old site, will be deprecated soon
Authentication
Routes marked with the OAuth label require a valid OAuth2 token for access.
More information about applications you have registered and granted permissions to can be found here.
The API supports the following grant types:
Before you can use the osu!api, you will need to
Registering an OAuth application
Before you can get an OAuth token, you will need to register an OAuth application on your account settings page
To register an OAuth application you will need to provide the:
Name Description Application Name This is the name that will be visible to users of your application. The name of your application cannot be changed. Application Callback URL The URL in your application where users will be sent after authorization.
The Application Callback URL is required when for using Authorization Codes. This may be left blank if you are only using Client Credentials Grants.
Your new OAuth application will have a Client ID and Client Secret ; the Client Secret is like a password for your OAuth application, it should be kept private and do not share it with anyone else.
Authorization Code Grant
The flow to authorize users for your application is:
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:
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:
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.
Make sure to replace <> 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:
Name Description chat.write Allows sending chat messages on a user’s behalf. delegate Allows acting as the owner of a client; only available for Client Credentials Grant. forum.write Allows creating and editing forum posts on a user’s behalf. friends.read Allows reading of the user’s friend list. identify Allows reading of the public profile of the user ( /me ). public Allows reading of publicly available data on behalf of the user.
identify is the default scope for the Authorization Code Grant and always implicitly provided. The Client Credentials Grant does not currently have any default scopes.
Routes marked with lazer are intended for use by the osu!lazer client and not currently available for use with Authorization Code or Client Credentials grants.
Using the chat.write scope requires either
Managing OAuth applications
Your account settings page will show your registered OAuth applications, and all the OAuth applications you have granted permissions to.
Reset Client Secret
You can generate a new Client Secret by choosing to «Reset client secret», however, this will disable all access tokens issued for the application.
Beatmaps
Lookup Beatmap
Response format
Get a User Beatmap score
Return a User’s score on a Beatmap
Response Format
The position returned depends on the requested mode and mods.
Get a User Beatmap scores
Return a User’s scores on a Beatmap
Response Format
Get Beatmap scores
Returns the top scores for a beatmap
Response Format
Get Beatmap scores (temp)
Returns the top scores for a beatmap from newer client.
This is a temporary endpoint.
Response Format
Get Beatmaps
Returns list of beatmaps.
Response format
Field Type Description beatmaps BeatmapCompact[] Includes: beatmapset (with ratings), failtimes, max_combo.
Get Beatmap
Gets beatmap data for the specified beatmap ID.
Response format
Returns Beatmap object. Following attributes are included in the response object when applicable,
Attribute Notes beatmapset Includes ratings property. failtimes max_combo
Get Beatmap Attributes
Returns difficulty attributes of beatmap with specific mode and mods combination.
Response format
Beatmapset Discussions
Get Beatmapset Discussion Posts
Returns the posts of beatmapset discussions.
Response Format
Get Beatmapset Discussion Votes
Returns the votes given to beatmapset discussions.
Response Format
Get Beatmapset Discussions
Returns a list of beatmapset discussions.
Response Format
Changelog
Get Changelog Build
Returns details of the specified build.
Response Format
Get Changelog Listing
Returns a listing of update streams, builds, and changelog entries.
Response Format
Lookup Changelog Build
Returns details of the specified build.
Response Format
Create New PM
This endpoint allows you to create a new PM channel.
Response Format
Field Type new_channel_id channel_id of newly created ChatChannel presence array of ChatChannel message the sent ChatMessage
This endpoint will only allow the creation of PMs initially, group chat support will come later.
Get Updates
This endpoint returns new messages since the given message_id along with updated channel ‘presence’ data.
Response Format
Get Channel Messages
This endpoint returns the chat messages for a specific channel.
Response Format
Returns an array of ChatMessage
Send Message to Channel
This endpoint returns the chat messages for a specific channel.
Response Format
Join Channel
This endpoint allows you to join a public or multiplayer channel.
Response Format
Returns the joined ChatChannel.
Leave Channel
This endpoint allows you to leave a public channel.
Response Format
Mark Channel as Read
Response Format
Get Channel List
This endpoint returns a list of all joinable public channels.
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.
Response Format
Returns ChatChannel with recent_messages attribute. Note that in the case of PM s, 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.
Response Format
Field Type Description channel ChatChannel users UserCompact Users are only visible for PM channels.
Comments
Get Comments
Returns a list comments and their replies up to 2 levels deep.
Response Format
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.
Response Format
Get a Comment
Gets a comment and its replies up to 2 levels deep.
Response Format
Edit Comment
Edit an existing comment.
Response Format
Delete Comment
Deletes the specified comment.
Response Format
Add Comment vote
Upvotes a comment.
Response Format
Remove Comment vote
Un-upvotes a comment.
Response Format
Forum
Reply Topic
Create a post replying to the specified topic.
Response Format
ForumPost with body included.
Create Topic
Create a new topic.
Response Format
Get Topic and Posts
Get topic and its posts.
Response Format
Edit Topic
Edit topic. Only title can be edited through this endpoint.
Response Format
Edit Post
Edit specified forum post.
Response Format
ForumPost with body included.
Search
Searches users and wiki pages.
Response Format
SearchResult
Multiplayer
Get User High Score
Returns detail of highest score of specified user and the surrounding scores.
Response Format
Get Scores
Returns a list of scores for specified playlist item.
Response Format
Get a Score
Returns detail of specified score and the surrounding scores.
Response Format
Get News Listing
Returns a list of news posts and related metadata.
Response Format
Get News Post
Returns details of the specified news post.
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.
Response Format
Returns an object containing Notification and other related attributes.
Field Type has_more boolean whether or not there are more notifications notifications array of Notification unread_count total unread notifications notification_endpoint url to connect to websocket server
Mark Notifications as Read
This endpoint allows you to mark notifications read.
Response Format
OAuth Tokens
Revoke current token
Revokes currently authenticated token.
Ranking
Get Ranking
Gets the current ranking for the specified type and game mode.
Response Format
Get Spotlights
Gets the list of spotlights.
Response Format
Undocumented
/beatmaps//solo/scores
/beatmaps//solo/scores//beatmapsets/events
/beatmapsets//favourites
/chat/presence
/matches
/matches//rooms//rooms//users//rooms//users//rooms//leaderboard
/rooms//playlist//scores
/rooms//playlist//scores//reports
/rooms
/rooms//seasonal-backgrounds
/scores///download
/scores///beatmapsets/search//beatmapsets/lookup
/beatmapsets//friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
Similar to Get User but with authenticated user (token owner) as user id.
Response format
Additionally, statistics_rulesets is included, containing statistics for all rulesets.
Get User Kudosu
Returns kudosu history.
Response format
Get User Scores
This endpoint returns the scores of specified user.
Response format
Array of Score. Following attributes are included in the response object when applicable.
Get User Beatmaps
Returns the beatmaps of specified user.
Type Notes favourite graveyard loved most_played pending Previously unranked ranked Previously ranked_and_approved
Response format
Array of BeatmapPlaycount when type is most_played ; array of Beatmapset, otherwise.
Get User Recent Activity
Returns recent activity.
Response format
Get User
This endpoint returns the detail of specified user.
Response format
Returns User object. The following optional attributes on UserCompact are included:
Get Users
Returns list of users.
Response format
Field Type Description users UserCompact[] Includes: country, cover, groups, statistics_rulesets.
Get Wiki Page
The wiki article or image data.
Response Format
Notification Websocket
Connection
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:
Field Type Description event string See below
logout event
Server will disconnect session after sending this event so don’t try to reconnect.
Field Type Description event string logout
new event
New notification. See Notification object for notification types.
Field Type Description event string new data Notification
read event
Notification has been read.
Field Type Description event string read ids number[] id of Notifications which are read
Object Structures
Beatmap
Represent a beatmap. This extends BeatmapCompact with additional attributes.
Field Type Description accuracy float ar float beatmapset_id integer bpm float? convert boolean count_circles integer count_sliders integer count_spinners integer cs float deleted_at Timestamp? drain float hit_length integer is_scoreable boolean last_updated Timestamp mode_int integer passcount integer playcount integer ranked integer See Rank status for list of possible values. url string
BeatmapCompact
Represent a beatmap.
Field Type Description beatmapset_id integer difficulty_rating float id integer mode GameMode status string See Rank status for list of possible values. total_length integer user_id integer version string
Field Type Description beatmapset Beatmapset|BeatmapsetCompact|null Beatmapset for Beatmap object, BeatmapsetCompact for BeatmapCompact object. null if the beatmap doesn’t have associated beatmapset (e.g. deleted). checksum string? failtimes Failtimes max_combo integer
Failtimes
All fields are optional but there’s always at least one field returned.
Field Type Description exit integer[]? Array of length 100. fail integer[]? Array of length 100.
BeatmapDifficultyAttributes
Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.
Field Type max_combo integer star_rating float
Field Type aim_difficulty float approach_rate float flashlight_difficulty float overall_difficulty float slider_factor float speed_difficulty float
taiko
Field Type stamina_difficulty float rhythm_difficulty float colour_difficulty float approach_rate float great_hit_window float
fruits
mania
Field Type great_hit_window float score_multiplier float
BeatmapPlaycount
Represent the playcount of a beatmap.
Field Type Description beatmap_id number beatmap BeatmapCompact? beatmapset BeatmapsetCompact? count number
BeatmapScores
Field Type Description scores Score[] The list of top scores for the beatmap in descending order. userScore BeatmapUserScore? The score of the current user. This is not returned if the current user does not have a score. Note: will be moved to user_score in the future
BeatmapUserScore
Field Type Description position number The position of the score within the requested beatmap ranking. score Score The details of the score.
Beatmapset
Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.
Field Type Description availability.download_disabled boolean availability.more_information string? bpm float can_be_hyped boolean creator string Username of the mapper at the time of beatmapset creation. discussion_locked boolean hype.current integer hype.required integer is_scoreable boolean last_updated Timestamp legacy_thread_url string? nominations.current integer nominations.required integer ranked integer See Rank status for list of possible values. ranked_date Timestamp? source string storyboard boolean submitted_date Timestamp? tags string
The following attributes are always included as well:
Field has_favourited
BeatmapsetCompact
Represents a beatmapset.
Field Type Description artist string artist_unicode string covers Covers creator string favourite_count number id number nsfw boolean play_count number preview_url string source string status string title string title_unicode string user_id number video boolean
Those fields are optional.
Field Type Description beatmaps Beatmap[] converts current_user_attributes description discussions events genre has_favourited boolean language nominations ratings recent_favourites related_users user
Covers
Field Type cover string cover@2x string card string card@2x string list string list@2x string slimcover string slimcover@2x string
Rank status
The possible values are denoted either as integer or string.
Integer String -2 graveyard -1 wip 0 pending 1 ranked 2 approved 3 qualified 4 loved
BeatmapsetDiscussion
Represents a Beatmapset modding discussion.
Field Type Description beatmap BeatmapCompact? beatmap_id number? beatmapset BeatmapsetCompact? beatmapset_id number can_be_resolved boolean can_grant_kudosu boolean created_at Timestamp current_user_attributes CurrentUserAttributes deleted_at Timestamp? deleted_by_id number? id number kudosu_denied boolean last_post_at Timestamp message_type MessageType parent_id number? posts BeatmapsetDiscussionPost[]? resolved boolean starting_post BeatmapsetDiscussionPost? timestamp number? updated_at Timestamp user_id number
MessageType
Name Description hype mapper_note praise problem review suggestion
BeatmapsetDiscussionPost
Field Type Description beatmapset_discussion_id number created_at Timestamp deleted_at Timestamp? deleted_by_id number? id number last_editor_id number? message string system boolean updated_at Timestamp user_id number
BeatmapsetDiscussionVote
Field Type Description beatmapset_discussion_id number created_at Timestamp id number score number updated_at Timestamp user_id number
Build
Field Type created_at Timestamp display_version string id number update_stream UpdateStream? users number version string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes changelog_entries ChangelogEntry[] If the build has no changelog entries, a placeholder is generated. versions Versions
Versions
ChangelogEntry
Field Type category string created_at Timestamp? github_pull_request_id number? github_url string? id number? major boolean repository string? title string? type string url string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes github_user GithubUser If the changelog entry has no GitHub user, a placeholder is generated. message string? Entry message in Markdown format. Embedded HTML is allowed. message_html string? Entry message in HTML format.
ChatChannel
Represents an individual chat «channel» in the game.
Channel Types
Type Permission Check for Joining/Messaging PUBLIC PRIVATE is player in the allowed groups? (channel.allowed_groups) MULTIPLAYER is player currently in the mp game? SPECTATOR TEMPORARY deprecated PM see below (user_channels) GROUP is player in channel? (user_channels)
For PMs, two factors are taken into account:
ChatMessage
Represents an individual Message within a ChatChannel.
Field Type Description message_id number unique identifier for message sender_id number user_id of the sender channel_id number channel_id of where the message was sent timestamp string when the message was sent, ISO-8601 content string message content is_action boolean was this an action? i.e. /me dances sender UserCompact embedded UserCompact object to save additional api lookups
Comment
Represents an single comment.
Field Type Description commentable_id number ID of the object the comment is attached to commentable_type string type of object the comment is attached to created_at string ISO 8601 date deleted_at string? ISO 8601 date if the comment was deleted; null, otherwise edited_at string? ISO 8601 date if the comment was edited; null, otherwise edited_by_id number? user id of the user that edited the post; null, otherwise id number the ID of the comment legacy_name string? username displayed on legacy comments message string? markdown of the comment’s content message_html string? html version of the comment’s content parent_id number? ID of the comment’s parent pinned boolean Pin status of the comment replies_count number number of replies to the comment updated_at string ISO 8601 date user_id number user ID of the poster votes_count number number of votes
CommentBundle
Comments and related data.
Field Type Description commentable_meta CommentableMeta[] ID of the object the comment is attached to comments Comment[] Array of comments ordered according to sort ; cursor Cursor has_more boolean If there are more comments or replies available has_more_id number? included_comments Comment[] Related comments; e.g. parent comments and nested replies pinned_comments Comment[]? Pinned comments sort string one of the CommentSort types top_level_count number? Number of comments at the top level. Not returned for replies. total number? Total number of comments. Not retuned for replies. user_follow boolean is the current user watching the comment thread? user_votes number[] IDs of the comments in the bundle the current user has upvoted users UserCompact[] array of users related to the comments
CommentSort
Type Sort Fields new created_at (descending), id (descending) old created_at (ascending), id (ascending) top votes_count (descending), created_at (descending), id (descending)
Building cursor for comments listing
The returned response will be for comments after the specified sort fields.
For example, use last loaded comment for the fields value to load more comments. Also make sure to use same sort and parent_id values.
CommentableMeta
Metadata of the object that a comment is attached to.
Field Type Description id number the ID of the object title string display title type string the type of the object url string url of the object
CurrentUserAttributes
An object listing various related permissions and states for the current user, related to the object it is attached to.
BeatmapsetDiscussionPermissions
TODO: needs a better name.
Name Description can_destroy Can delete the discussion. can_reopen Can reopen the discussion. can_moderate_kudosu Can allow or deny kudosu. can_resolve Can resolve the discussion. vote_score Current vote given to the discussion.
ChatChannelUserAttributes
Name Type Description can_message boolean Can send messages to this channel. can_message_error string? Reason messages cannot be sent to this channel last_read_id number message_id of last message read.
Cursor
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.
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
osu!api open beta
Нет аккаунта?
osu!api open beta
I’ve had an API available for a while but until now it has been on a private on-request basis. In order to try and make developing third party services which expand and support osu!, I have added an API key setup and started to document the API.
Documentation will be expanded as I find time to do so! If anyone currently using the API is able to help expand the documentation then please do.
comentarinformal wrote:
Before I spam it with requests that might not exist, is there anything to get user’s information?
(Also, is there anything to login users from this page in other places?)
There is /api/get_user
Gonna write an entry with the information I have about it.
Is there a fair use limit? (e.g. no more than XX requests per day)
For get_user, I suppose there is a mode parameter for getting user information for Taiko, CtB and osu!mania? Or do I have to file an issue in GitHub? Nevermind, I found it, the parameter to add is called «m» I have edited the GitHub wiki.
Oh well. I have some questions:
Are only the beatmap and user endpoints available?
The parameter «since» in /get_beatmap how I need to pass the time on it? UTC or unix timestamp?
Do I need to pass the key on the wiki’s API too?
Edit: What the countX values mean? Number of beatmaps?
comentarinformal wrote:
Before I spam it with requests that might not exist, is there anything to get user’s information?
(Also, is there anything to login users from this page in other places?)
I guess I’ll update my userbar too when I find some time.
Damnae wrote:
I guess I’ll update my userbar too when I find some time.
I registered it for osu!userbar, but I also use it for my «Big ugly white signature», they are not on the same webserver, but it works fine
I belive only you and peppy can see the name you used, too.
(Yes I took my lazyness off, it was not that long to update ^^)
@Repflez: I tried using your API-powered signature and I get something weird.
Since I only aim for SS, I have 100% Accuracy all the time, and the Accuracy display is weird.
(I now know that despite having all-SS records, the note hit count for getting 50s and 100s are still counted all the time )
Winshley wrote:
@Repflez: I tried using your API-powered signature and I get something weird.
Since I only aim for SS, I have 100% Accuracy all the time, and the Accuracy display is weird.
(I now know that despite having all-SS records, the note hit count for getting 50s and 100s are still counted all the time )
So that’s what the CountX values mean. Thanks for that. I already went and changed the accuracy to show a centered «100% Accuracy» if it’s 100. Forget that. I ditched the bar on it and used the extra space for showing the PP.
(I love how the 300 count ended overlaping the border)
Repflez wrote:
So that’s what the CountX values mean. Thanks for that.
Yeah. At first I thought that there was something wrong with the API showing 50s and 100s despite having 100% Accuracy, until I actually calculated all 300s + 100s + 50s = «Total Hits» on our profile.
About the 300 overlap though, it does need some fix:
When you reached 10 millions of 300 hits, the last number is cut off. Cookiezi has 17 millions of 300 hits.
I’m not sure how the level bar breaking happens though. I was thinking that it probably because I don’t have any ranked score on osu!mania?
[Archived] getting osu! api token
Нет аккаунта?
[Archived] getting osu! api token
here is the website I am currently using this for https://osu-api-crap.minecreeper0913.repl.co
well since the project I am using is all python and not javascript I am using a new tab browser to just test it and so far the code I am using is
url = («https://osu.ppy.sh/oauth/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=%s» % (code))
the &code=%s is basically just grabbing the code that has been given back by oauth and using that as the url, when I am testing it though I am actually using my code
Never share your client secret, it’s secret for a reason. I would recommend resetting it ASAP.
Are you just typing that URL into your browser or are you actually sending it as a post request with whatever python code you have? Typing the URL into your browser won’t work.
The token endpoint takes the parameters in the body of the request, not as query parameters. You are also missing some parameters, like redirect_uri and grant_type.
If you are using python’s requests library, you can do something like this:
Might have some syntax errors because I wrote that from memory and didn’t check anything in an IDE or by running it.
You can try without specifying the content type in your headers, it might work without it. Very simply, the content type header describes what type of content or data is being sent. As far as I recall, the server is expecting that content type but I could be wrong.
now starting to realize that I might have done this a bit wrong, this is the first time I have used an API for something so everything I am doing is new to me.
So the first thing that is happening is that you press the login to link your osu API to the website, then it grabs your code and redirects you to the home website with the code in the url for example http://www.website.com/code=j9838r9y82g9438gh8243hg384hg, and it is supposed to use that, but when in testing it just returns favicon.ico, and I don’t know what that is or means so I might have to change my get request, another issue is but how would I make it get that auth code?
I don’t know anything about the project you are working on, so unfortunately I don’t think I can really answer any of the questions you’re asking.
I don’t know what you mean by a favicon being returned and I also don’t know what you are using the handle the backend of your site, so I can’t specifically tell you how to grab the code. Whatever you are using should have some way of getting query parameters from the URL.
Oauth2 is a very standardized and should be nearly the same everywhere that uses it. osu! is no exception. I would highly recommend looking up and reading about the authorization code flow that you are trying to use here. There should be a ton of resources and maybe a few code examples as well.
There might not be any videos specific to osu!’s API, but there are definitely Oauth2 tutorial videos and examples out there in probably every programming language, which is what you are dealing with right now.
For example, here is a video I found after a quick Google search that is using Python. I can’t fully comment on its quality since I just skimmed through it, but the general flow that the creator of the video goes over seems like it will at least cover how OAuth2 works in general, even if it’s not in the context of osu!’s API.
And even if you don’t really like reading, there are still some pretty good resources you can use that might help in addition to watching a video. Like this and this for example. Again, I’ve only skimmed through these, but they also seem to be pretty good.
here is the code I use:
NOTE I did not actually use SECRET as the secret I have it as SECRET because its secret
/beatmapsets/events
/beatmapsets//favourites
/chat/presence
/matches
/matches//rooms//rooms//users//rooms//users//rooms//leaderboard
/rooms//playlist//scores
/rooms//playlist//scores//reports
/rooms
/rooms//seasonal-backgrounds
/scores///download
/scores///beatmapsets/search//beatmapsets/lookup
/beatmapsets//friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
Similar to Get User but with authenticated user (token owner) as user id.
Response format
Additionally, statistics_rulesets is included, containing statistics for all rulesets.
Get User Kudosu
Returns kudosu history.
Response format
Get User Scores
This endpoint returns the scores of specified user.
Response format
Array of Score. Following attributes are included in the response object when applicable.
Get User Beatmaps
Returns the beatmaps of specified user.
Type Notes favourite graveyard loved most_played pending Previously unranked ranked Previously ranked_and_approved
Response format
Array of BeatmapPlaycount when type is most_played ; array of Beatmapset, otherwise.
Get User Recent Activity
Returns recent activity.
Response format
Get User
This endpoint returns the detail of specified user.
Response format
Returns User object. The following optional attributes on UserCompact are included:
Get Users
Returns list of users.
Response format
Field Type Description users UserCompact[] Includes: country, cover, groups, statistics_rulesets.
Get Wiki Page
The wiki article or image data.
Response Format
Notification Websocket
Connection
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:
Field Type Description event string See below
logout event
Server will disconnect session after sending this event so don’t try to reconnect.
Field Type Description event string logout
new event
New notification. See Notification object for notification types.
Field Type Description event string new data Notification
read event
Notification has been read.
Field Type Description event string read ids number[] id of Notifications which are read
Object Structures
Beatmap
Represent a beatmap. This extends BeatmapCompact with additional attributes.
Field Type Description accuracy float ar float beatmapset_id integer bpm float? convert boolean count_circles integer count_sliders integer count_spinners integer cs float deleted_at Timestamp? drain float hit_length integer is_scoreable boolean last_updated Timestamp mode_int integer passcount integer playcount integer ranked integer See Rank status for list of possible values. url string
BeatmapCompact
Represent a beatmap.
Field Type Description beatmapset_id integer difficulty_rating float id integer mode GameMode status string See Rank status for list of possible values. total_length integer user_id integer version string
Field Type Description beatmapset Beatmapset|BeatmapsetCompact|null Beatmapset for Beatmap object, BeatmapsetCompact for BeatmapCompact object. null if the beatmap doesn’t have associated beatmapset (e.g. deleted). checksum string? failtimes Failtimes max_combo integer
Failtimes
All fields are optional but there’s always at least one field returned.
Field Type Description exit integer[]? Array of length 100. fail integer[]? Array of length 100.
BeatmapDifficultyAttributes
Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.
Field Type max_combo integer star_rating float
Field Type aim_difficulty float approach_rate float flashlight_difficulty float overall_difficulty float slider_factor float speed_difficulty float
taiko
Field Type stamina_difficulty float rhythm_difficulty float colour_difficulty float approach_rate float great_hit_window float
fruits
mania
Field Type great_hit_window float score_multiplier float
BeatmapPlaycount
Represent the playcount of a beatmap.
Field Type Description beatmap_id number beatmap BeatmapCompact? beatmapset BeatmapsetCompact? count number
BeatmapScores
Field Type Description scores Score[] The list of top scores for the beatmap in descending order. userScore BeatmapUserScore? The score of the current user. This is not returned if the current user does not have a score. Note: will be moved to user_score in the future
BeatmapUserScore
Field Type Description position number The position of the score within the requested beatmap ranking. score Score The details of the score.
Beatmapset
Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.
Field Type Description availability.download_disabled boolean availability.more_information string? bpm float can_be_hyped boolean creator string Username of the mapper at the time of beatmapset creation. discussion_locked boolean hype.current integer hype.required integer is_scoreable boolean last_updated Timestamp legacy_thread_url string? nominations.current integer nominations.required integer ranked integer See Rank status for list of possible values. ranked_date Timestamp? source string storyboard boolean submitted_date Timestamp? tags string
The following attributes are always included as well:
Field has_favourited
BeatmapsetCompact
Represents a beatmapset.
Field Type Description artist string artist_unicode string covers Covers creator string favourite_count number id number nsfw boolean play_count number preview_url string source string status string title string title_unicode string user_id number video boolean
Those fields are optional.
Field Type Description beatmaps Beatmap[] converts current_user_attributes description discussions events genre has_favourited boolean language nominations ratings recent_favourites related_users user
Covers
Field Type cover string cover@2x string card string card@2x string list string list@2x string slimcover string slimcover@2x string
Rank status
The possible values are denoted either as integer or string.
Integer String -2 graveyard -1 wip 0 pending 1 ranked 2 approved 3 qualified 4 loved
BeatmapsetDiscussion
Represents a Beatmapset modding discussion.
Field Type Description beatmap BeatmapCompact? beatmap_id number? beatmapset BeatmapsetCompact? beatmapset_id number can_be_resolved boolean can_grant_kudosu boolean created_at Timestamp current_user_attributes CurrentUserAttributes deleted_at Timestamp? deleted_by_id number? id number kudosu_denied boolean last_post_at Timestamp message_type MessageType parent_id number? posts BeatmapsetDiscussionPost[]? resolved boolean starting_post BeatmapsetDiscussionPost? timestamp number? updated_at Timestamp user_id number
MessageType
Name Description hype mapper_note praise problem review suggestion
BeatmapsetDiscussionPost
Field Type Description beatmapset_discussion_id number created_at Timestamp deleted_at Timestamp? deleted_by_id number? id number last_editor_id number? message string system boolean updated_at Timestamp user_id number
BeatmapsetDiscussionVote
Field Type Description beatmapset_discussion_id number created_at Timestamp id number score number updated_at Timestamp user_id number
Build
Field Type created_at Timestamp display_version string id number update_stream UpdateStream? users number version string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes changelog_entries ChangelogEntry[] If the build has no changelog entries, a placeholder is generated. versions Versions
Versions
ChangelogEntry
Field Type category string created_at Timestamp? github_pull_request_id number? github_url string? id number? major boolean repository string? title string? type string url string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes github_user GithubUser If the changelog entry has no GitHub user, a placeholder is generated. message string? Entry message in Markdown format. Embedded HTML is allowed. message_html string? Entry message in HTML format.
ChatChannel
Represents an individual chat «channel» in the game.
Channel Types
Type Permission Check for Joining/Messaging PUBLIC PRIVATE is player in the allowed groups? (channel.allowed_groups) MULTIPLAYER is player currently in the mp game? SPECTATOR TEMPORARY deprecated PM see below (user_channels) GROUP is player in channel? (user_channels)
For PMs, two factors are taken into account:
ChatMessage
Represents an individual Message within a ChatChannel.
Field Type Description message_id number unique identifier for message sender_id number user_id of the sender channel_id number channel_id of where the message was sent timestamp string when the message was sent, ISO-8601 content string message content is_action boolean was this an action? i.e. /me dances sender UserCompact embedded UserCompact object to save additional api lookups
Comment
Represents an single comment.
Field Type Description commentable_id number ID of the object the comment is attached to commentable_type string type of object the comment is attached to created_at string ISO 8601 date deleted_at string? ISO 8601 date if the comment was deleted; null, otherwise edited_at string? ISO 8601 date if the comment was edited; null, otherwise edited_by_id number? user id of the user that edited the post; null, otherwise id number the ID of the comment legacy_name string? username displayed on legacy comments message string? markdown of the comment’s content message_html string? html version of the comment’s content parent_id number? ID of the comment’s parent pinned boolean Pin status of the comment replies_count number number of replies to the comment updated_at string ISO 8601 date user_id number user ID of the poster votes_count number number of votes
CommentBundle
Comments and related data.
Field Type Description commentable_meta CommentableMeta[] ID of the object the comment is attached to comments Comment[] Array of comments ordered according to sort ; cursor Cursor has_more boolean If there are more comments or replies available has_more_id number? included_comments Comment[] Related comments; e.g. parent comments and nested replies pinned_comments Comment[]? Pinned comments sort string one of the CommentSort types top_level_count number? Number of comments at the top level. Not returned for replies. total number? Total number of comments. Not retuned for replies. user_follow boolean is the current user watching the comment thread? user_votes number[] IDs of the comments in the bundle the current user has upvoted users UserCompact[] array of users related to the comments
CommentSort
Type Sort Fields new created_at (descending), id (descending) old created_at (ascending), id (ascending) top votes_count (descending), created_at (descending), id (descending)
Building cursor for comments listing
The returned response will be for comments after the specified sort fields.
For example, use last loaded comment for the fields value to load more comments. Also make sure to use same sort and parent_id values.
CommentableMeta
Metadata of the object that a comment is attached to.
Field Type Description id number the ID of the object title string display title type string the type of the object url string url of the object
CurrentUserAttributes
An object listing various related permissions and states for the current user, related to the object it is attached to.
BeatmapsetDiscussionPermissions
TODO: needs a better name.
Name Description can_destroy Can delete the discussion. can_reopen Can reopen the discussion. can_moderate_kudosu Can allow or deny kudosu. can_resolve Can resolve the discussion. vote_score Current vote given to the discussion.
ChatChannelUserAttributes
Name Type Description can_message boolean Can send messages to this channel. can_message_error string? Reason messages cannot be sent to this channel last_read_id number message_id of last message read.
Cursor
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.
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
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-07-06
2022-06-08
2021-10-28
2021-09-01
2021-08-11
2021-06-14
2021-06-09
2021-04-20
2021-02-25
2020-09-08
2020-08-28
2020-05-01
2020-02-18
2019-10-09
2019-07-18
Endpoint
Base URL
The base URL is: https://osu.ppy.sh/api/[version]/
API Versions
This is combined with the base endpoint to determine where requests should be sent.
Version Status v2 current (not yet public, consider unstable and expect breaking changes) v1 legacy api provided by the old site, will be deprecated soon
Authentication
Routes marked with the OAuth label require a valid OAuth2 token for access.
More information about applications you have registered and granted permissions to can be found here.
The API supports the following grant types:
Before you can use the osu!api, you will need to
Registering an OAuth application
Before you can get an OAuth token, you will need to register an OAuth application on your account settings page
To register an OAuth application you will need to provide the:
Name Description Application Name This is the name that will be visible to users of your application. The name of your application cannot be changed. Application Callback URL The URL in your application where users will be sent after authorization.
The Application Callback URL is required when for using Authorization Codes. This may be left blank if you are only using Client Credentials Grants.
Your new OAuth application will have a Client ID and Client Secret ; the Client Secret is like a password for your OAuth application, it should be kept private and do not share it with anyone else.
Authorization Code Grant
The flow to authorize users for your application is:
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:
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:
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.
Make sure to replace <> 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:
Name Description chat.write Allows sending chat messages on a user’s behalf. delegate Allows acting as the owner of a client; only available for Client Credentials Grant. forum.write Allows creating and editing forum posts on a user’s behalf. friends.read Allows reading of the user’s friend list. identify Allows reading of the public profile of the user ( /me ). public Allows reading of publicly available data on behalf of the user.
identify is the default scope for the Authorization Code Grant and always implicitly provided. The Client Credentials Grant does not currently have any default scopes.
Routes marked with lazer are intended for use by the osu!lazer client and not currently available for use with Authorization Code or Client Credentials grants.
Using the chat.write scope requires either
Managing OAuth applications
Your account settings page will show your registered OAuth applications, and all the OAuth applications you have granted permissions to.
Reset Client Secret
You can generate a new Client Secret by choosing to «Reset client secret», however, this will disable all access tokens issued for the application.
Beatmaps
Lookup Beatmap
Response format
Get a User Beatmap score
Return a User’s score on a Beatmap
Response Format
The position returned depends on the requested mode and mods.
Get a User Beatmap scores
Return a User’s scores on a Beatmap
Response Format
Get Beatmap scores
Returns the top scores for a beatmap
Response Format
Get Beatmap scores (temp)
Returns the top scores for a beatmap from newer client.
This is a temporary endpoint.
Response Format
Get Beatmaps
Returns list of beatmaps.
Response format
Field Type Description beatmaps BeatmapCompact[] Includes: beatmapset (with ratings), failtimes, max_combo.
Get Beatmap
Gets beatmap data for the specified beatmap ID.
Response format
Returns Beatmap object. Following attributes are included in the response object when applicable,
Attribute Notes beatmapset Includes ratings property. failtimes max_combo
Get Beatmap Attributes
Returns difficulty attributes of beatmap with specific mode and mods combination.
Response format
Beatmapset Discussions
Get Beatmapset Discussion Posts
Returns the posts of beatmapset discussions.
Response Format
Get Beatmapset Discussion Votes
Returns the votes given to beatmapset discussions.
Response Format
Get Beatmapset Discussions
Returns a list of beatmapset discussions.
Response Format
Changelog
Get Changelog Build
Returns details of the specified build.
Response Format
Get Changelog Listing
Returns a listing of update streams, builds, and changelog entries.
Response Format
Lookup Changelog Build
Returns details of the specified build.
Response Format
Create New PM
This endpoint allows you to create a new PM channel.
Response Format
Field Type new_channel_id channel_id of newly created ChatChannel presence array of ChatChannel message the sent ChatMessage
This endpoint will only allow the creation of PMs initially, group chat support will come later.
Get Updates
This endpoint returns new messages since the given message_id along with updated channel ‘presence’ data.
Response Format
Get Channel Messages
This endpoint returns the chat messages for a specific channel.
Response Format
Returns an array of ChatMessage
Send Message to Channel
This endpoint returns the chat messages for a specific channel.
Response Format
Join Channel
This endpoint allows you to join a public or multiplayer channel.
Response Format
Returns the joined ChatChannel.
Leave Channel
This endpoint allows you to leave a public channel.
Response Format
Mark Channel as Read
Response Format
Get Channel List
This endpoint returns a list of all joinable public channels.
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.
Response Format
Returns ChatChannel with recent_messages attribute. Note that in the case of PM s, 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.
Response Format
Field Type Description channel ChatChannel users UserCompact Users are only visible for PM channels.
Comments
Get Comments
Returns a list comments and their replies up to 2 levels deep.
Response Format
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.
Response Format
Get a Comment
Gets a comment and its replies up to 2 levels deep.
Response Format
Edit Comment
Edit an existing comment.
Response Format
Delete Comment
Deletes the specified comment.
Response Format
Add Comment vote
Upvotes a comment.
Response Format
Remove Comment vote
Un-upvotes a comment.
Response Format
Forum
Reply Topic
Create a post replying to the specified topic.
Response Format
ForumPost with body included.
Create Topic
Create a new topic.
Response Format
Get Topic and Posts
Get topic and its posts.
Response Format
Edit Topic
Edit topic. Only title can be edited through this endpoint.
Response Format
Edit Post
Edit specified forum post.
Response Format
ForumPost with body included.
Search
Searches users and wiki pages.
Response Format
SearchResult
Multiplayer
Get User High Score
Returns detail of highest score of specified user and the surrounding scores.
Response Format
Get Scores
Returns a list of scores for specified playlist item.
Response Format
Get a Score
Returns detail of specified score and the surrounding scores.
Response Format
Get News Listing
Returns a list of news posts and related metadata.
Response Format
Get News Post
Returns details of the specified news post.
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.
Response Format
Returns an object containing Notification and other related attributes.
Field Type has_more boolean whether or not there are more notifications notifications array of Notification unread_count total unread notifications notification_endpoint url to connect to websocket server
Mark Notifications as Read
This endpoint allows you to mark notifications read.
Response Format
OAuth Tokens
Revoke current token
Revokes currently authenticated token.
Ranking
Get Ranking
Gets the current ranking for the specified type and game mode.
Response Format
Get Spotlights
Gets the list of spotlights.
Response Format
Undocumented
/beatmaps//solo/scores
/beatmaps//solo/scores//beatmapsets/events
/beatmapsets//favourites
/chat/presence
/matches
/matches//rooms//rooms//users//rooms//users//rooms//leaderboard
/rooms//playlist//scores
/rooms//playlist//scores//reports
/rooms
/rooms//seasonal-backgrounds
/scores///download
/scores///beatmapsets/search//beatmapsets/lookup
/beatmapsets//friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
Similar to Get User but with authenticated user (token owner) as user id.
Response format
Additionally, statistics_rulesets is included, containing statistics for all rulesets.
Get User Kudosu
Returns kudosu history.
Response format
Get User Scores
This endpoint returns the scores of specified user.
Response format
Array of Score. Following attributes are included in the response object when applicable.
Get User Beatmaps
Returns the beatmaps of specified user.
Type Notes favourite graveyard loved most_played pending Previously unranked ranked Previously ranked_and_approved
Response format
Array of BeatmapPlaycount when type is most_played ; array of Beatmapset, otherwise.
Get User Recent Activity
Returns recent activity.
Response format
Get User
This endpoint returns the detail of specified user.
Response format
Returns User object. The following optional attributes on UserCompact are included:
Get Users
Returns list of users.
Response format
Field Type Description users UserCompact[] Includes: country, cover, groups, statistics_rulesets.
Get Wiki Page
The wiki article or image data.
Response Format
Notification Websocket
Connection
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:
Field Type Description event string See below
logout event
Server will disconnect session after sending this event so don’t try to reconnect.
Field Type Description event string logout
new event
New notification. See Notification object for notification types.
Field Type Description event string new data Notification
read event
Notification has been read.
Field Type Description event string read ids number[] id of Notifications which are read
Object Structures
Beatmap
Represent a beatmap. This extends BeatmapCompact with additional attributes.
Field Type Description accuracy float ar float beatmapset_id integer bpm float? convert boolean count_circles integer count_sliders integer count_spinners integer cs float deleted_at Timestamp? drain float hit_length integer is_scoreable boolean last_updated Timestamp mode_int integer passcount integer playcount integer ranked integer See Rank status for list of possible values. url string
BeatmapCompact
Represent a beatmap.
Field Type Description beatmapset_id integer difficulty_rating float id integer mode GameMode status string See Rank status for list of possible values. total_length integer user_id integer version string
Field Type Description beatmapset Beatmapset|BeatmapsetCompact|null Beatmapset for Beatmap object, BeatmapsetCompact for BeatmapCompact object. null if the beatmap doesn’t have associated beatmapset (e.g. deleted). checksum string? failtimes Failtimes max_combo integer
Failtimes
All fields are optional but there’s always at least one field returned.
Field Type Description exit integer[]? Array of length 100. fail integer[]? Array of length 100.
BeatmapDifficultyAttributes
Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.
Field Type max_combo integer star_rating float
Field Type aim_difficulty float approach_rate float flashlight_difficulty float overall_difficulty float slider_factor float speed_difficulty float
taiko
Field Type stamina_difficulty float rhythm_difficulty float colour_difficulty float approach_rate float great_hit_window float
fruits
mania
Field Type great_hit_window float score_multiplier float
BeatmapPlaycount
Represent the playcount of a beatmap.
Field Type Description beatmap_id number beatmap BeatmapCompact? beatmapset BeatmapsetCompact? count number
BeatmapScores
Field Type Description scores Score[] The list of top scores for the beatmap in descending order. userScore BeatmapUserScore? The score of the current user. This is not returned if the current user does not have a score. Note: will be moved to user_score in the future
BeatmapUserScore
Field Type Description position number The position of the score within the requested beatmap ranking. score Score The details of the score.
Beatmapset
Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.
Field Type Description availability.download_disabled boolean availability.more_information string? bpm float can_be_hyped boolean creator string Username of the mapper at the time of beatmapset creation. discussion_locked boolean hype.current integer hype.required integer is_scoreable boolean last_updated Timestamp legacy_thread_url string? nominations.current integer nominations.required integer ranked integer See Rank status for list of possible values. ranked_date Timestamp? source string storyboard boolean submitted_date Timestamp? tags string
The following attributes are always included as well:
Field has_favourited
BeatmapsetCompact
Represents a beatmapset.
Field Type Description artist string artist_unicode string covers Covers creator string favourite_count number id number nsfw boolean play_count number preview_url string source string status string title string title_unicode string user_id number video boolean
Those fields are optional.
Field Type Description beatmaps Beatmap[] converts current_user_attributes description discussions events genre has_favourited boolean language nominations ratings recent_favourites related_users user
Covers
Field Type cover string cover@2x string card string card@2x string list string list@2x string slimcover string slimcover@2x string
Rank status
The possible values are denoted either as integer or string.
Integer String -2 graveyard -1 wip 0 pending 1 ranked 2 approved 3 qualified 4 loved
BeatmapsetDiscussion
Represents a Beatmapset modding discussion.
Field Type Description beatmap BeatmapCompact? beatmap_id number? beatmapset BeatmapsetCompact? beatmapset_id number can_be_resolved boolean can_grant_kudosu boolean created_at Timestamp current_user_attributes CurrentUserAttributes deleted_at Timestamp? deleted_by_id number? id number kudosu_denied boolean last_post_at Timestamp message_type MessageType parent_id number? posts BeatmapsetDiscussionPost[]? resolved boolean starting_post BeatmapsetDiscussionPost? timestamp number? updated_at Timestamp user_id number
MessageType
Name Description hype mapper_note praise problem review suggestion
BeatmapsetDiscussionPost
Field Type Description beatmapset_discussion_id number created_at Timestamp deleted_at Timestamp? deleted_by_id number? id number last_editor_id number? message string system boolean updated_at Timestamp user_id number
BeatmapsetDiscussionVote
Field Type Description beatmapset_discussion_id number created_at Timestamp id number score number updated_at Timestamp user_id number
Build
Field Type created_at Timestamp display_version string id number update_stream UpdateStream? users number version string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes changelog_entries ChangelogEntry[] If the build has no changelog entries, a placeholder is generated. versions Versions
Versions
ChangelogEntry
Field Type category string created_at Timestamp? github_pull_request_id number? github_url string? id number? major boolean repository string? title string? type string url string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes github_user GithubUser If the changelog entry has no GitHub user, a placeholder is generated. message string? Entry message in Markdown format. Embedded HTML is allowed. message_html string? Entry message in HTML format.
ChatChannel
Represents an individual chat «channel» in the game.
Channel Types
Type Permission Check for Joining/Messaging PUBLIC PRIVATE is player in the allowed groups? (channel.allowed_groups) MULTIPLAYER is player currently in the mp game? SPECTATOR TEMPORARY deprecated PM see below (user_channels) GROUP is player in channel? (user_channels)
For PMs, two factors are taken into account:
ChatMessage
Represents an individual Message within a ChatChannel.
Field Type Description message_id number unique identifier for message sender_id number user_id of the sender channel_id number channel_id of where the message was sent timestamp string when the message was sent, ISO-8601 content string message content is_action boolean was this an action? i.e. /me dances sender UserCompact embedded UserCompact object to save additional api lookups
Comment
Represents an single comment.
Field Type Description commentable_id number ID of the object the comment is attached to commentable_type string type of object the comment is attached to created_at string ISO 8601 date deleted_at string? ISO 8601 date if the comment was deleted; null, otherwise edited_at string? ISO 8601 date if the comment was edited; null, otherwise edited_by_id number? user id of the user that edited the post; null, otherwise id number the ID of the comment legacy_name string? username displayed on legacy comments message string? markdown of the comment’s content message_html string? html version of the comment’s content parent_id number? ID of the comment’s parent pinned boolean Pin status of the comment replies_count number number of replies to the comment updated_at string ISO 8601 date user_id number user ID of the poster votes_count number number of votes
CommentBundle
Comments and related data.
Field Type Description commentable_meta CommentableMeta[] ID of the object the comment is attached to comments Comment[] Array of comments ordered according to sort ; cursor Cursor has_more boolean If there are more comments or replies available has_more_id number? included_comments Comment[] Related comments; e.g. parent comments and nested replies pinned_comments Comment[]? Pinned comments sort string one of the CommentSort types top_level_count number? Number of comments at the top level. Not returned for replies. total number? Total number of comments. Not retuned for replies. user_follow boolean is the current user watching the comment thread? user_votes number[] IDs of the comments in the bundle the current user has upvoted users UserCompact[] array of users related to the comments
CommentSort
Type Sort Fields new created_at (descending), id (descending) old created_at (ascending), id (ascending) top votes_count (descending), created_at (descending), id (descending)
Building cursor for comments listing
The returned response will be for comments after the specified sort fields.
For example, use last loaded comment for the fields value to load more comments. Also make sure to use same sort and parent_id values.
CommentableMeta
Metadata of the object that a comment is attached to.
Field Type Description id number the ID of the object title string display title type string the type of the object url string url of the object
CurrentUserAttributes
An object listing various related permissions and states for the current user, related to the object it is attached to.
BeatmapsetDiscussionPermissions
TODO: needs a better name.
Name Description can_destroy Can delete the discussion. can_reopen Can reopen the discussion. can_moderate_kudosu Can allow or deny kudosu. can_resolve Can resolve the discussion. vote_score Current vote given to the discussion.
ChatChannelUserAttributes
Name Type Description can_message boolean Can send messages to this channel. can_message_error string? Reason messages cannot be sent to this channel last_read_id number message_id of last message read.
Cursor
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.
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
osu!api open beta
Нет аккаунта?
osu!api open beta
I’ve had an API available for a while but until now it has been on a private on-request basis. In order to try and make developing third party services which expand and support osu!, I have added an API key setup and started to document the API.
Documentation will be expanded as I find time to do so! If anyone currently using the API is able to help expand the documentation then please do.
comentarinformal wrote:
Before I spam it with requests that might not exist, is there anything to get user’s information?
(Also, is there anything to login users from this page in other places?)
There is /api/get_user
Gonna write an entry with the information I have about it.
Is there a fair use limit? (e.g. no more than XX requests per day)
For get_user, I suppose there is a mode parameter for getting user information for Taiko, CtB and osu!mania? Or do I have to file an issue in GitHub? Nevermind, I found it, the parameter to add is called «m» I have edited the GitHub wiki.
Oh well. I have some questions:
Are only the beatmap and user endpoints available?
The parameter «since» in /get_beatmap how I need to pass the time on it? UTC or unix timestamp?
Do I need to pass the key on the wiki’s API too?
Edit: What the countX values mean? Number of beatmaps?
comentarinformal wrote:
Before I spam it with requests that might not exist, is there anything to get user’s information?
(Also, is there anything to login users from this page in other places?)
I guess I’ll update my userbar too when I find some time.
Damnae wrote:
I guess I’ll update my userbar too when I find some time.
I registered it for osu!userbar, but I also use it for my «Big ugly white signature», they are not on the same webserver, but it works fine
I belive only you and peppy can see the name you used, too.
(Yes I took my lazyness off, it was not that long to update ^^)
@Repflez: I tried using your API-powered signature and I get something weird.
Since I only aim for SS, I have 100% Accuracy all the time, and the Accuracy display is weird.
(I now know that despite having all-SS records, the note hit count for getting 50s and 100s are still counted all the time )
Winshley wrote:
@Repflez: I tried using your API-powered signature and I get something weird.
Since I only aim for SS, I have 100% Accuracy all the time, and the Accuracy display is weird.
(I now know that despite having all-SS records, the note hit count for getting 50s and 100s are still counted all the time )
So that’s what the CountX values mean. Thanks for that. I already went and changed the accuracy to show a centered «100% Accuracy» if it’s 100. Forget that. I ditched the bar on it and used the extra space for showing the PP.
(I love how the 300 count ended overlaping the border)
Repflez wrote:
So that’s what the CountX values mean. Thanks for that.
Yeah. At first I thought that there was something wrong with the API showing 50s and 100s despite having 100% Accuracy, until I actually calculated all 300s + 100s + 50s = «Total Hits» on our profile.
About the 300 overlap though, it does need some fix:
When you reached 10 millions of 300 hits, the last number is cut off. Cookiezi has 17 millions of 300 hits.
I’m not sure how the level bar breaking happens though. I was thinking that it probably because I don’t have any ranked score on osu!mania?
[Archived] getting osu! api token
Нет аккаунта?
[Archived] getting osu! api token
here is the website I am currently using this for https://osu-api-crap.minecreeper0913.repl.co
well since the project I am using is all python and not javascript I am using a new tab browser to just test it and so far the code I am using is
url = («https://osu.ppy.sh/oauth/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=%s» % (code))
the &code=%s is basically just grabbing the code that has been given back by oauth and using that as the url, when I am testing it though I am actually using my code
Never share your client secret, it’s secret for a reason. I would recommend resetting it ASAP.
Are you just typing that URL into your browser or are you actually sending it as a post request with whatever python code you have? Typing the URL into your browser won’t work.
The token endpoint takes the parameters in the body of the request, not as query parameters. You are also missing some parameters, like redirect_uri and grant_type.
If you are using python’s requests library, you can do something like this:
Might have some syntax errors because I wrote that from memory and didn’t check anything in an IDE or by running it.
You can try without specifying the content type in your headers, it might work without it. Very simply, the content type header describes what type of content or data is being sent. As far as I recall, the server is expecting that content type but I could be wrong.
now starting to realize that I might have done this a bit wrong, this is the first time I have used an API for something so everything I am doing is new to me.
So the first thing that is happening is that you press the login to link your osu API to the website, then it grabs your code and redirects you to the home website with the code in the url for example http://www.website.com/code=j9838r9y82g9438gh8243hg384hg, and it is supposed to use that, but when in testing it just returns favicon.ico, and I don’t know what that is or means so I might have to change my get request, another issue is but how would I make it get that auth code?
I don’t know anything about the project you are working on, so unfortunately I don’t think I can really answer any of the questions you’re asking.
I don’t know what you mean by a favicon being returned and I also don’t know what you are using the handle the backend of your site, so I can’t specifically tell you how to grab the code. Whatever you are using should have some way of getting query parameters from the URL.
Oauth2 is a very standardized and should be nearly the same everywhere that uses it. osu! is no exception. I would highly recommend looking up and reading about the authorization code flow that you are trying to use here. There should be a ton of resources and maybe a few code examples as well.
There might not be any videos specific to osu!’s API, but there are definitely Oauth2 tutorial videos and examples out there in probably every programming language, which is what you are dealing with right now.
For example, here is a video I found after a quick Google search that is using Python. I can’t fully comment on its quality since I just skimmed through it, but the general flow that the creator of the video goes over seems like it will at least cover how OAuth2 works in general, even if it’s not in the context of osu!’s API.
And even if you don’t really like reading, there are still some pretty good resources you can use that might help in addition to watching a video. Like this and this for example. Again, I’ve only skimmed through these, but they also seem to be pretty good.
here is the code I use:
NOTE I did not actually use SECRET as the secret I have it as SECRET because its secret
/rooms//users//rooms//users//rooms//leaderboard
/rooms//playlist//scores
/rooms//playlist//scores//reports
/rooms
/rooms//seasonal-backgrounds
/scores///download
/scores///beatmapsets/search//beatmapsets/lookup
/beatmapsets//friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
Similar to Get User but with authenticated user (token owner) as user id.
Response format
Additionally, statistics_rulesets is included, containing statistics for all rulesets.
Get User Kudosu
Returns kudosu history.
Response format
Get User Scores
This endpoint returns the scores of specified user.
Response format
Array of Score. Following attributes are included in the response object when applicable.
Get User Beatmaps
Returns the beatmaps of specified user.
Type Notes favourite graveyard loved most_played pending Previously unranked ranked Previously ranked_and_approved
Response format
Array of BeatmapPlaycount when type is most_played ; array of Beatmapset, otherwise.
Get User Recent Activity
Returns recent activity.
Response format
Get User
This endpoint returns the detail of specified user.
Response format
Returns User object. The following optional attributes on UserCompact are included:
Get Users
Returns list of users.
Response format
Field Type Description users UserCompact[] Includes: country, cover, groups, statistics_rulesets.
Get Wiki Page
The wiki article or image data.
Response Format
Notification Websocket
Connection
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:
Field Type Description event string See below
logout event
Server will disconnect session after sending this event so don’t try to reconnect.
Field Type Description event string logout
new event
New notification. See Notification object for notification types.
Field Type Description event string new data Notification
read event
Notification has been read.
Field Type Description event string read ids number[] id of Notifications which are read
Object Structures
Beatmap
Represent a beatmap. This extends BeatmapCompact with additional attributes.
Field Type Description accuracy float ar float beatmapset_id integer bpm float? convert boolean count_circles integer count_sliders integer count_spinners integer cs float deleted_at Timestamp? drain float hit_length integer is_scoreable boolean last_updated Timestamp mode_int integer passcount integer playcount integer ranked integer See Rank status for list of possible values. url string
BeatmapCompact
Represent a beatmap.
Field Type Description beatmapset_id integer difficulty_rating float id integer mode GameMode status string See Rank status for list of possible values. total_length integer user_id integer version string
Field Type Description beatmapset Beatmapset|BeatmapsetCompact|null Beatmapset for Beatmap object, BeatmapsetCompact for BeatmapCompact object. null if the beatmap doesn’t have associated beatmapset (e.g. deleted). checksum string? failtimes Failtimes max_combo integer
Failtimes
All fields are optional but there’s always at least one field returned.
Field Type Description exit integer[]? Array of length 100. fail integer[]? Array of length 100.
BeatmapDifficultyAttributes
Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.
Field Type max_combo integer star_rating float
Field Type aim_difficulty float approach_rate float flashlight_difficulty float overall_difficulty float slider_factor float speed_difficulty float
taiko
Field Type stamina_difficulty float rhythm_difficulty float colour_difficulty float approach_rate float great_hit_window float
fruits
mania
Field Type great_hit_window float score_multiplier float
BeatmapPlaycount
Represent the playcount of a beatmap.
Field Type Description beatmap_id number beatmap BeatmapCompact? beatmapset BeatmapsetCompact? count number
BeatmapScores
Field Type Description scores Score[] The list of top scores for the beatmap in descending order. userScore BeatmapUserScore? The score of the current user. This is not returned if the current user does not have a score. Note: will be moved to user_score in the future
BeatmapUserScore
Field Type Description position number The position of the score within the requested beatmap ranking. score Score The details of the score.
Beatmapset
Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.
Field Type Description availability.download_disabled boolean availability.more_information string? bpm float can_be_hyped boolean creator string Username of the mapper at the time of beatmapset creation. discussion_locked boolean hype.current integer hype.required integer is_scoreable boolean last_updated Timestamp legacy_thread_url string? nominations.current integer nominations.required integer ranked integer See Rank status for list of possible values. ranked_date Timestamp? source string storyboard boolean submitted_date Timestamp? tags string
The following attributes are always included as well:
Field has_favourited
BeatmapsetCompact
Represents a beatmapset.
Field Type Description artist string artist_unicode string covers Covers creator string favourite_count number id number nsfw boolean play_count number preview_url string source string status string title string title_unicode string user_id number video boolean
Those fields are optional.
Field Type Description beatmaps Beatmap[] converts current_user_attributes description discussions events genre has_favourited boolean language nominations ratings recent_favourites related_users user
Covers
Field Type cover string cover@2x string card string card@2x string list string list@2x string slimcover string slimcover@2x string
Rank status
The possible values are denoted either as integer or string.
Integer String -2 graveyard -1 wip 0 pending 1 ranked 2 approved 3 qualified 4 loved
BeatmapsetDiscussion
Represents a Beatmapset modding discussion.
Field Type Description beatmap BeatmapCompact? beatmap_id number? beatmapset BeatmapsetCompact? beatmapset_id number can_be_resolved boolean can_grant_kudosu boolean created_at Timestamp current_user_attributes CurrentUserAttributes deleted_at Timestamp? deleted_by_id number? id number kudosu_denied boolean last_post_at Timestamp message_type MessageType parent_id number? posts BeatmapsetDiscussionPost[]? resolved boolean starting_post BeatmapsetDiscussionPost? timestamp number? updated_at Timestamp user_id number
MessageType
Name Description hype mapper_note praise problem review suggestion
BeatmapsetDiscussionPost
Field Type Description beatmapset_discussion_id number created_at Timestamp deleted_at Timestamp? deleted_by_id number? id number last_editor_id number? message string system boolean updated_at Timestamp user_id number
BeatmapsetDiscussionVote
Field Type Description beatmapset_discussion_id number created_at Timestamp id number score number updated_at Timestamp user_id number
Build
Field Type created_at Timestamp display_version string id number update_stream UpdateStream? users number version string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes changelog_entries ChangelogEntry[] If the build has no changelog entries, a placeholder is generated. versions Versions
Versions
ChangelogEntry
Field Type category string created_at Timestamp? github_pull_request_id number? github_url string? id number? major boolean repository string? title string? type string url string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes github_user GithubUser If the changelog entry has no GitHub user, a placeholder is generated. message string? Entry message in Markdown format. Embedded HTML is allowed. message_html string? Entry message in HTML format.
ChatChannel
Represents an individual chat «channel» in the game.
Channel Types
Type Permission Check for Joining/Messaging PUBLIC PRIVATE is player in the allowed groups? (channel.allowed_groups) MULTIPLAYER is player currently in the mp game? SPECTATOR TEMPORARY deprecated PM see below (user_channels) GROUP is player in channel? (user_channels)
For PMs, two factors are taken into account:
ChatMessage
Represents an individual Message within a ChatChannel.
Field Type Description message_id number unique identifier for message sender_id number user_id of the sender channel_id number channel_id of where the message was sent timestamp string when the message was sent, ISO-8601 content string message content is_action boolean was this an action? i.e. /me dances sender UserCompact embedded UserCompact object to save additional api lookups
Comment
Represents an single comment.
Field Type Description commentable_id number ID of the object the comment is attached to commentable_type string type of object the comment is attached to created_at string ISO 8601 date deleted_at string? ISO 8601 date if the comment was deleted; null, otherwise edited_at string? ISO 8601 date if the comment was edited; null, otherwise edited_by_id number? user id of the user that edited the post; null, otherwise id number the ID of the comment legacy_name string? username displayed on legacy comments message string? markdown of the comment’s content message_html string? html version of the comment’s content parent_id number? ID of the comment’s parent pinned boolean Pin status of the comment replies_count number number of replies to the comment updated_at string ISO 8601 date user_id number user ID of the poster votes_count number number of votes
CommentBundle
Comments and related data.
Field Type Description commentable_meta CommentableMeta[] ID of the object the comment is attached to comments Comment[] Array of comments ordered according to sort ; cursor Cursor has_more boolean If there are more comments or replies available has_more_id number? included_comments Comment[] Related comments; e.g. parent comments and nested replies pinned_comments Comment[]? Pinned comments sort string one of the CommentSort types top_level_count number? Number of comments at the top level. Not returned for replies. total number? Total number of comments. Not retuned for replies. user_follow boolean is the current user watching the comment thread? user_votes number[] IDs of the comments in the bundle the current user has upvoted users UserCompact[] array of users related to the comments
CommentSort
Type Sort Fields new created_at (descending), id (descending) old created_at (ascending), id (ascending) top votes_count (descending), created_at (descending), id (descending)
Building cursor for comments listing
The returned response will be for comments after the specified sort fields.
For example, use last loaded comment for the fields value to load more comments. Also make sure to use same sort and parent_id values.
CommentableMeta
Metadata of the object that a comment is attached to.
Field Type Description id number the ID of the object title string display title type string the type of the object url string url of the object
CurrentUserAttributes
An object listing various related permissions and states for the current user, related to the object it is attached to.
BeatmapsetDiscussionPermissions
TODO: needs a better name.
Name Description can_destroy Can delete the discussion. can_reopen Can reopen the discussion. can_moderate_kudosu Can allow or deny kudosu. can_resolve Can resolve the discussion. vote_score Current vote given to the discussion.
ChatChannelUserAttributes
Name Type Description can_message boolean Can send messages to this channel. can_message_error string? Reason messages cannot be sent to this channel last_read_id number message_id of last message read.
Cursor
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.
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
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-07-06
2022-06-08
2021-10-28
2021-09-01
2021-08-11
2021-06-14
2021-06-09
2021-04-20
2021-02-25
2020-09-08
2020-08-28
2020-05-01
2020-02-18
2019-10-09
2019-07-18
Endpoint
Base URL
The base URL is: https://osu.ppy.sh/api/[version]/
API Versions
This is combined with the base endpoint to determine where requests should be sent.
Version Status v2 current (not yet public, consider unstable and expect breaking changes) v1 legacy api provided by the old site, will be deprecated soon
Authentication
Routes marked with the OAuth label require a valid OAuth2 token for access.
More information about applications you have registered and granted permissions to can be found here.
The API supports the following grant types:
Before you can use the osu!api, you will need to
Registering an OAuth application
Before you can get an OAuth token, you will need to register an OAuth application on your account settings page
To register an OAuth application you will need to provide the:
Name Description Application Name This is the name that will be visible to users of your application. The name of your application cannot be changed. Application Callback URL The URL in your application where users will be sent after authorization.
The Application Callback URL is required when for using Authorization Codes. This may be left blank if you are only using Client Credentials Grants.
Your new OAuth application will have a Client ID and Client Secret ; the Client Secret is like a password for your OAuth application, it should be kept private and do not share it with anyone else.
Authorization Code Grant
The flow to authorize users for your application is:
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:
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:
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.
Make sure to replace <> 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:
Name Description chat.write Allows sending chat messages on a user’s behalf. delegate Allows acting as the owner of a client; only available for Client Credentials Grant. forum.write Allows creating and editing forum posts on a user’s behalf. friends.read Allows reading of the user’s friend list. identify Allows reading of the public profile of the user ( /me ). public Allows reading of publicly available data on behalf of the user.
identify is the default scope for the Authorization Code Grant and always implicitly provided. The Client Credentials Grant does not currently have any default scopes.
Routes marked with lazer are intended for use by the osu!lazer client and not currently available for use with Authorization Code or Client Credentials grants.
Using the chat.write scope requires either
Managing OAuth applications
Your account settings page will show your registered OAuth applications, and all the OAuth applications you have granted permissions to.
Reset Client Secret
You can generate a new Client Secret by choosing to «Reset client secret», however, this will disable all access tokens issued for the application.
Beatmaps
Lookup Beatmap
Response format
Get a User Beatmap score
Return a User’s score on a Beatmap
Response Format
The position returned depends on the requested mode and mods.
Get a User Beatmap scores
Return a User’s scores on a Beatmap
Response Format
Get Beatmap scores
Returns the top scores for a beatmap
Response Format
Get Beatmap scores (temp)
Returns the top scores for a beatmap from newer client.
This is a temporary endpoint.
Response Format
Get Beatmaps
Returns list of beatmaps.
Response format
Field Type Description beatmaps BeatmapCompact[] Includes: beatmapset (with ratings), failtimes, max_combo.
Get Beatmap
Gets beatmap data for the specified beatmap ID.
Response format
Returns Beatmap object. Following attributes are included in the response object when applicable,
Attribute Notes beatmapset Includes ratings property. failtimes max_combo
Get Beatmap Attributes
Returns difficulty attributes of beatmap with specific mode and mods combination.
Response format
Beatmapset Discussions
Get Beatmapset Discussion Posts
Returns the posts of beatmapset discussions.
Response Format
Get Beatmapset Discussion Votes
Returns the votes given to beatmapset discussions.
Response Format
Get Beatmapset Discussions
Returns a list of beatmapset discussions.
Response Format
Changelog
Get Changelog Build
Returns details of the specified build.
Response Format
Get Changelog Listing
Returns a listing of update streams, builds, and changelog entries.
Response Format
Lookup Changelog Build
Returns details of the specified build.
Response Format
Create New PM
This endpoint allows you to create a new PM channel.
Response Format
Field Type new_channel_id channel_id of newly created ChatChannel presence array of ChatChannel message the sent ChatMessage
This endpoint will only allow the creation of PMs initially, group chat support will come later.
Get Updates
This endpoint returns new messages since the given message_id along with updated channel ‘presence’ data.
Response Format
Get Channel Messages
This endpoint returns the chat messages for a specific channel.
Response Format
Returns an array of ChatMessage
Send Message to Channel
This endpoint returns the chat messages for a specific channel.
Response Format
Join Channel
This endpoint allows you to join a public or multiplayer channel.
Response Format
Returns the joined ChatChannel.
Leave Channel
This endpoint allows you to leave a public channel.
Response Format
Mark Channel as Read
Response Format
Get Channel List
This endpoint returns a list of all joinable public channels.
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.
Response Format
Returns ChatChannel with recent_messages attribute. Note that in the case of PM s, 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.
Response Format
Field Type Description channel ChatChannel users UserCompact Users are only visible for PM channels.
Comments
Get Comments
Returns a list comments and their replies up to 2 levels deep.
Response Format
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.
Response Format
Get a Comment
Gets a comment and its replies up to 2 levels deep.
Response Format
Edit Comment
Edit an existing comment.
Response Format
Delete Comment
Deletes the specified comment.
Response Format
Add Comment vote
Upvotes a comment.
Response Format
Remove Comment vote
Un-upvotes a comment.
Response Format
Forum
Reply Topic
Create a post replying to the specified topic.
Response Format
ForumPost with body included.
Create Topic
Create a new topic.
Response Format
Get Topic and Posts
Get topic and its posts.
Response Format
Edit Topic
Edit topic. Only title can be edited through this endpoint.
Response Format
Edit Post
Edit specified forum post.
Response Format
ForumPost with body included.
Search
Searches users and wiki pages.
Response Format
SearchResult
Multiplayer
Get User High Score
Returns detail of highest score of specified user and the surrounding scores.
Response Format
Get Scores
Returns a list of scores for specified playlist item.
Response Format
Get a Score
Returns detail of specified score and the surrounding scores.
Response Format
Get News Listing
Returns a list of news posts and related metadata.
Response Format
Get News Post
Returns details of the specified news post.
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.
Response Format
Returns an object containing Notification and other related attributes.
Field Type has_more boolean whether or not there are more notifications notifications array of Notification unread_count total unread notifications notification_endpoint url to connect to websocket server
Mark Notifications as Read
This endpoint allows you to mark notifications read.
Response Format
OAuth Tokens
Revoke current token
Revokes currently authenticated token.
Ranking
Get Ranking
Gets the current ranking for the specified type and game mode.
Response Format
Get Spotlights
Gets the list of spotlights.
Response Format
Undocumented
/beatmaps//solo/scores
/beatmaps//solo/scores//beatmapsets/events
/beatmapsets//favourites
/chat/presence
/matches
/matches//rooms//rooms//users//rooms//users//rooms//leaderboard
/rooms//playlist//scores
/rooms//playlist//scores//reports
/rooms
/rooms//seasonal-backgrounds
/scores///download
/scores///beatmapsets/search//beatmapsets/lookup
/beatmapsets//friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
Similar to Get User but with authenticated user (token owner) as user id.
Response format
Additionally, statistics_rulesets is included, containing statistics for all rulesets.
Get User Kudosu
Returns kudosu history.
Response format
Get User Scores
This endpoint returns the scores of specified user.
Response format
Array of Score. Following attributes are included in the response object when applicable.
Get User Beatmaps
Returns the beatmaps of specified user.
Type Notes favourite graveyard loved most_played pending Previously unranked ranked Previously ranked_and_approved
Response format
Array of BeatmapPlaycount when type is most_played ; array of Beatmapset, otherwise.
Get User Recent Activity
Returns recent activity.
Response format
Get User
This endpoint returns the detail of specified user.
Response format
Returns User object. The following optional attributes on UserCompact are included:
Get Users
Returns list of users.
Response format
Field Type Description users UserCompact[] Includes: country, cover, groups, statistics_rulesets.
Get Wiki Page
The wiki article or image data.
Response Format
Notification Websocket
Connection
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:
Field Type Description event string See below
logout event
Server will disconnect session after sending this event so don’t try to reconnect.
Field Type Description event string logout
new event
New notification. See Notification object for notification types.
Field Type Description event string new data Notification
read event
Notification has been read.
Field Type Description event string read ids number[] id of Notifications which are read
Object Structures
Beatmap
Represent a beatmap. This extends BeatmapCompact with additional attributes.
Field Type Description accuracy float ar float beatmapset_id integer bpm float? convert boolean count_circles integer count_sliders integer count_spinners integer cs float deleted_at Timestamp? drain float hit_length integer is_scoreable boolean last_updated Timestamp mode_int integer passcount integer playcount integer ranked integer See Rank status for list of possible values. url string
BeatmapCompact
Represent a beatmap.
Field Type Description beatmapset_id integer difficulty_rating float id integer mode GameMode status string See Rank status for list of possible values. total_length integer user_id integer version string
Field Type Description beatmapset Beatmapset|BeatmapsetCompact|null Beatmapset for Beatmap object, BeatmapsetCompact for BeatmapCompact object. null if the beatmap doesn’t have associated beatmapset (e.g. deleted). checksum string? failtimes Failtimes max_combo integer
Failtimes
All fields are optional but there’s always at least one field returned.
Field Type Description exit integer[]? Array of length 100. fail integer[]? Array of length 100.
BeatmapDifficultyAttributes
Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.
Field Type max_combo integer star_rating float
Field Type aim_difficulty float approach_rate float flashlight_difficulty float overall_difficulty float slider_factor float speed_difficulty float
taiko
Field Type stamina_difficulty float rhythm_difficulty float colour_difficulty float approach_rate float great_hit_window float
fruits
mania
Field Type great_hit_window float score_multiplier float
BeatmapPlaycount
Represent the playcount of a beatmap.
Field Type Description beatmap_id number beatmap BeatmapCompact? beatmapset BeatmapsetCompact? count number
BeatmapScores
Field Type Description scores Score[] The list of top scores for the beatmap in descending order. userScore BeatmapUserScore? The score of the current user. This is not returned if the current user does not have a score. Note: will be moved to user_score in the future
BeatmapUserScore
Field Type Description position number The position of the score within the requested beatmap ranking. score Score The details of the score.
Beatmapset
Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.
Field Type Description availability.download_disabled boolean availability.more_information string? bpm float can_be_hyped boolean creator string Username of the mapper at the time of beatmapset creation. discussion_locked boolean hype.current integer hype.required integer is_scoreable boolean last_updated Timestamp legacy_thread_url string? nominations.current integer nominations.required integer ranked integer See Rank status for list of possible values. ranked_date Timestamp? source string storyboard boolean submitted_date Timestamp? tags string
The following attributes are always included as well:
Field has_favourited
BeatmapsetCompact
Represents a beatmapset.
Field Type Description artist string artist_unicode string covers Covers creator string favourite_count number id number nsfw boolean play_count number preview_url string source string status string title string title_unicode string user_id number video boolean
Those fields are optional.
Field Type Description beatmaps Beatmap[] converts current_user_attributes description discussions events genre has_favourited boolean language nominations ratings recent_favourites related_users user
Covers
Field Type cover string cover@2x string card string card@2x string list string list@2x string slimcover string slimcover@2x string
Rank status
The possible values are denoted either as integer or string.
Integer String -2 graveyard -1 wip 0 pending 1 ranked 2 approved 3 qualified 4 loved
BeatmapsetDiscussion
Represents a Beatmapset modding discussion.
Field Type Description beatmap BeatmapCompact? beatmap_id number? beatmapset BeatmapsetCompact? beatmapset_id number can_be_resolved boolean can_grant_kudosu boolean created_at Timestamp current_user_attributes CurrentUserAttributes deleted_at Timestamp? deleted_by_id number? id number kudosu_denied boolean last_post_at Timestamp message_type MessageType parent_id number? posts BeatmapsetDiscussionPost[]? resolved boolean starting_post BeatmapsetDiscussionPost? timestamp number? updated_at Timestamp user_id number
MessageType
Name Description hype mapper_note praise problem review suggestion
BeatmapsetDiscussionPost
Field Type Description beatmapset_discussion_id number created_at Timestamp deleted_at Timestamp? deleted_by_id number? id number last_editor_id number? message string system boolean updated_at Timestamp user_id number
BeatmapsetDiscussionVote
Field Type Description beatmapset_discussion_id number created_at Timestamp id number score number updated_at Timestamp user_id number
Build
Field Type created_at Timestamp display_version string id number update_stream UpdateStream? users number version string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes changelog_entries ChangelogEntry[] If the build has no changelog entries, a placeholder is generated. versions Versions
Versions
ChangelogEntry
Field Type category string created_at Timestamp? github_pull_request_id number? github_url string? id number? major boolean repository string? title string? type string url string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes github_user GithubUser If the changelog entry has no GitHub user, a placeholder is generated. message string? Entry message in Markdown format. Embedded HTML is allowed. message_html string? Entry message in HTML format.
ChatChannel
Represents an individual chat «channel» in the game.
Channel Types
Type Permission Check for Joining/Messaging PUBLIC PRIVATE is player in the allowed groups? (channel.allowed_groups) MULTIPLAYER is player currently in the mp game? SPECTATOR TEMPORARY deprecated PM see below (user_channels) GROUP is player in channel? (user_channels)
For PMs, two factors are taken into account:
ChatMessage
Represents an individual Message within a ChatChannel.
Field Type Description message_id number unique identifier for message sender_id number user_id of the sender channel_id number channel_id of where the message was sent timestamp string when the message was sent, ISO-8601 content string message content is_action boolean was this an action? i.e. /me dances sender UserCompact embedded UserCompact object to save additional api lookups
Comment
Represents an single comment.
Field Type Description commentable_id number ID of the object the comment is attached to commentable_type string type of object the comment is attached to created_at string ISO 8601 date deleted_at string? ISO 8601 date if the comment was deleted; null, otherwise edited_at string? ISO 8601 date if the comment was edited; null, otherwise edited_by_id number? user id of the user that edited the post; null, otherwise id number the ID of the comment legacy_name string? username displayed on legacy comments message string? markdown of the comment’s content message_html string? html version of the comment’s content parent_id number? ID of the comment’s parent pinned boolean Pin status of the comment replies_count number number of replies to the comment updated_at string ISO 8601 date user_id number user ID of the poster votes_count number number of votes
CommentBundle
Comments and related data.
Field Type Description commentable_meta CommentableMeta[] ID of the object the comment is attached to comments Comment[] Array of comments ordered according to sort ; cursor Cursor has_more boolean If there are more comments or replies available has_more_id number? included_comments Comment[] Related comments; e.g. parent comments and nested replies pinned_comments Comment[]? Pinned comments sort string one of the CommentSort types top_level_count number? Number of comments at the top level. Not returned for replies. total number? Total number of comments. Not retuned for replies. user_follow boolean is the current user watching the comment thread? user_votes number[] IDs of the comments in the bundle the current user has upvoted users UserCompact[] array of users related to the comments
CommentSort
Type Sort Fields new created_at (descending), id (descending) old created_at (ascending), id (ascending) top votes_count (descending), created_at (descending), id (descending)
Building cursor for comments listing
The returned response will be for comments after the specified sort fields.
For example, use last loaded comment for the fields value to load more comments. Also make sure to use same sort and parent_id values.
CommentableMeta
Metadata of the object that a comment is attached to.
Field Type Description id number the ID of the object title string display title type string the type of the object url string url of the object
CurrentUserAttributes
An object listing various related permissions and states for the current user, related to the object it is attached to.
BeatmapsetDiscussionPermissions
TODO: needs a better name.
Name Description can_destroy Can delete the discussion. can_reopen Can reopen the discussion. can_moderate_kudosu Can allow or deny kudosu. can_resolve Can resolve the discussion. vote_score Current vote given to the discussion.
ChatChannelUserAttributes
Name Type Description can_message boolean Can send messages to this channel. can_message_error string? Reason messages cannot be sent to this channel last_read_id number message_id of last message read.
Cursor
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.
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
osu!api open beta
Нет аккаунта?
osu!api open beta
I’ve had an API available for a while but until now it has been on a private on-request basis. In order to try and make developing third party services which expand and support osu!, I have added an API key setup and started to document the API.
Documentation will be expanded as I find time to do so! If anyone currently using the API is able to help expand the documentation then please do.
comentarinformal wrote:
Before I spam it with requests that might not exist, is there anything to get user’s information?
(Also, is there anything to login users from this page in other places?)
There is /api/get_user
Gonna write an entry with the information I have about it.
Is there a fair use limit? (e.g. no more than XX requests per day)
For get_user, I suppose there is a mode parameter for getting user information for Taiko, CtB and osu!mania? Or do I have to file an issue in GitHub? Nevermind, I found it, the parameter to add is called «m» I have edited the GitHub wiki.
Oh well. I have some questions:
Are only the beatmap and user endpoints available?
The parameter «since» in /get_beatmap how I need to pass the time on it? UTC or unix timestamp?
Do I need to pass the key on the wiki’s API too?
Edit: What the countX values mean? Number of beatmaps?
comentarinformal wrote:
Before I spam it with requests that might not exist, is there anything to get user’s information?
(Also, is there anything to login users from this page in other places?)
I guess I’ll update my userbar too when I find some time.
Damnae wrote:
I guess I’ll update my userbar too when I find some time.
I registered it for osu!userbar, but I also use it for my «Big ugly white signature», they are not on the same webserver, but it works fine
I belive only you and peppy can see the name you used, too.
(Yes I took my lazyness off, it was not that long to update ^^)
@Repflez: I tried using your API-powered signature and I get something weird.
Since I only aim for SS, I have 100% Accuracy all the time, and the Accuracy display is weird.
(I now know that despite having all-SS records, the note hit count for getting 50s and 100s are still counted all the time )
Winshley wrote:
@Repflez: I tried using your API-powered signature and I get something weird.
Since I only aim for SS, I have 100% Accuracy all the time, and the Accuracy display is weird.
(I now know that despite having all-SS records, the note hit count for getting 50s and 100s are still counted all the time )
So that’s what the CountX values mean. Thanks for that. I already went and changed the accuracy to show a centered «100% Accuracy» if it’s 100. Forget that. I ditched the bar on it and used the extra space for showing the PP.
(I love how the 300 count ended overlaping the border)
Repflez wrote:
So that’s what the CountX values mean. Thanks for that.
Yeah. At first I thought that there was something wrong with the API showing 50s and 100s despite having 100% Accuracy, until I actually calculated all 300s + 100s + 50s = «Total Hits» on our profile.
About the 300 overlap though, it does need some fix:
When you reached 10 millions of 300 hits, the last number is cut off. Cookiezi has 17 millions of 300 hits.
I’m not sure how the level bar breaking happens though. I was thinking that it probably because I don’t have any ranked score on osu!mania?
[Archived] getting osu! api token
Нет аккаунта?
[Archived] getting osu! api token
here is the website I am currently using this for https://osu-api-crap.minecreeper0913.repl.co
well since the project I am using is all python and not javascript I am using a new tab browser to just test it and so far the code I am using is
url = («https://osu.ppy.sh/oauth/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=%s» % (code))
the &code=%s is basically just grabbing the code that has been given back by oauth and using that as the url, when I am testing it though I am actually using my code
Never share your client secret, it’s secret for a reason. I would recommend resetting it ASAP.
Are you just typing that URL into your browser or are you actually sending it as a post request with whatever python code you have? Typing the URL into your browser won’t work.
The token endpoint takes the parameters in the body of the request, not as query parameters. You are also missing some parameters, like redirect_uri and grant_type.
If you are using python’s requests library, you can do something like this:
Might have some syntax errors because I wrote that from memory and didn’t check anything in an IDE or by running it.
You can try without specifying the content type in your headers, it might work without it. Very simply, the content type header describes what type of content or data is being sent. As far as I recall, the server is expecting that content type but I could be wrong.
now starting to realize that I might have done this a bit wrong, this is the first time I have used an API for something so everything I am doing is new to me.
So the first thing that is happening is that you press the login to link your osu API to the website, then it grabs your code and redirects you to the home website with the code in the url for example http://www.website.com/code=j9838r9y82g9438gh8243hg384hg, and it is supposed to use that, but when in testing it just returns favicon.ico, and I don’t know what that is or means so I might have to change my get request, another issue is but how would I make it get that auth code?
I don’t know anything about the project you are working on, so unfortunately I don’t think I can really answer any of the questions you’re asking.
I don’t know what you mean by a favicon being returned and I also don’t know what you are using the handle the backend of your site, so I can’t specifically tell you how to grab the code. Whatever you are using should have some way of getting query parameters from the URL.
Oauth2 is a very standardized and should be nearly the same everywhere that uses it. osu! is no exception. I would highly recommend looking up and reading about the authorization code flow that you are trying to use here. There should be a ton of resources and maybe a few code examples as well.
There might not be any videos specific to osu!’s API, but there are definitely Oauth2 tutorial videos and examples out there in probably every programming language, which is what you are dealing with right now.
For example, here is a video I found after a quick Google search that is using Python. I can’t fully comment on its quality since I just skimmed through it, but the general flow that the creator of the video goes over seems like it will at least cover how OAuth2 works in general, even if it’s not in the context of osu!’s API.
And even if you don’t really like reading, there are still some pretty good resources you can use that might help in addition to watching a video. Like this and this for example. Again, I’ve only skimmed through these, but they also seem to be pretty good.
here is the code I use:
NOTE I did not actually use SECRET as the secret I have it as SECRET because its secret
/rooms//users//rooms//leaderboard
/rooms//playlist//scores
/rooms//playlist//scores//reports
/rooms
/rooms//seasonal-backgrounds
/scores///download
/scores///beatmapsets/search//beatmapsets/lookup
/beatmapsets//friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
Similar to Get User but with authenticated user (token owner) as user id.
Response format
Additionally, statistics_rulesets is included, containing statistics for all rulesets.
Get User Kudosu
Returns kudosu history.
Response format
Get User Scores
This endpoint returns the scores of specified user.
Response format
Array of Score. Following attributes are included in the response object when applicable.
Get User Beatmaps
Returns the beatmaps of specified user.
Type Notes favourite graveyard loved most_played pending Previously unranked ranked Previously ranked_and_approved
Response format
Array of BeatmapPlaycount when type is most_played ; array of Beatmapset, otherwise.
Get User Recent Activity
Returns recent activity.
Response format
Get User
This endpoint returns the detail of specified user.
Response format
Returns User object. The following optional attributes on UserCompact are included:
Get Users
Returns list of users.
Response format
Field Type Description users UserCompact[] Includes: country, cover, groups, statistics_rulesets.
Get Wiki Page
The wiki article or image data.
Response Format
Notification Websocket
Connection
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:
Field Type Description event string See below
logout event
Server will disconnect session after sending this event so don’t try to reconnect.
Field Type Description event string logout
new event
New notification. See Notification object for notification types.
Field Type Description event string new data Notification
read event
Notification has been read.
Field Type Description event string read ids number[] id of Notifications which are read
Object Structures
Beatmap
Represent a beatmap. This extends BeatmapCompact with additional attributes.
Field Type Description accuracy float ar float beatmapset_id integer bpm float? convert boolean count_circles integer count_sliders integer count_spinners integer cs float deleted_at Timestamp? drain float hit_length integer is_scoreable boolean last_updated Timestamp mode_int integer passcount integer playcount integer ranked integer See Rank status for list of possible values. url string
BeatmapCompact
Represent a beatmap.
Field Type Description beatmapset_id integer difficulty_rating float id integer mode GameMode status string See Rank status for list of possible values. total_length integer user_id integer version string
Field Type Description beatmapset Beatmapset|BeatmapsetCompact|null Beatmapset for Beatmap object, BeatmapsetCompact for BeatmapCompact object. null if the beatmap doesn’t have associated beatmapset (e.g. deleted). checksum string? failtimes Failtimes max_combo integer
Failtimes
All fields are optional but there’s always at least one field returned.
Field Type Description exit integer[]? Array of length 100. fail integer[]? Array of length 100.
BeatmapDifficultyAttributes
Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.
Field Type max_combo integer star_rating float
Field Type aim_difficulty float approach_rate float flashlight_difficulty float overall_difficulty float slider_factor float speed_difficulty float
taiko
Field Type stamina_difficulty float rhythm_difficulty float colour_difficulty float approach_rate float great_hit_window float
fruits
mania
Field Type great_hit_window float score_multiplier float
BeatmapPlaycount
Represent the playcount of a beatmap.
Field Type Description beatmap_id number beatmap BeatmapCompact? beatmapset BeatmapsetCompact? count number
BeatmapScores
Field Type Description scores Score[] The list of top scores for the beatmap in descending order. userScore BeatmapUserScore? The score of the current user. This is not returned if the current user does not have a score. Note: will be moved to user_score in the future
BeatmapUserScore
Field Type Description position number The position of the score within the requested beatmap ranking. score Score The details of the score.
Beatmapset
Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.
Field Type Description availability.download_disabled boolean availability.more_information string? bpm float can_be_hyped boolean creator string Username of the mapper at the time of beatmapset creation. discussion_locked boolean hype.current integer hype.required integer is_scoreable boolean last_updated Timestamp legacy_thread_url string? nominations.current integer nominations.required integer ranked integer See Rank status for list of possible values. ranked_date Timestamp? source string storyboard boolean submitted_date Timestamp? tags string
The following attributes are always included as well:
Field has_favourited
BeatmapsetCompact
Represents a beatmapset.
Field Type Description artist string artist_unicode string covers Covers creator string favourite_count number id number nsfw boolean play_count number preview_url string source string status string title string title_unicode string user_id number video boolean
Those fields are optional.
Field Type Description beatmaps Beatmap[] converts current_user_attributes description discussions events genre has_favourited boolean language nominations ratings recent_favourites related_users user
Covers
Field Type cover string cover@2x string card string card@2x string list string list@2x string slimcover string slimcover@2x string
Rank status
The possible values are denoted either as integer or string.
Integer String -2 graveyard -1 wip 0 pending 1 ranked 2 approved 3 qualified 4 loved
BeatmapsetDiscussion
Represents a Beatmapset modding discussion.
Field Type Description beatmap BeatmapCompact? beatmap_id number? beatmapset BeatmapsetCompact? beatmapset_id number can_be_resolved boolean can_grant_kudosu boolean created_at Timestamp current_user_attributes CurrentUserAttributes deleted_at Timestamp? deleted_by_id number? id number kudosu_denied boolean last_post_at Timestamp message_type MessageType parent_id number? posts BeatmapsetDiscussionPost[]? resolved boolean starting_post BeatmapsetDiscussionPost? timestamp number? updated_at Timestamp user_id number
MessageType
Name Description hype mapper_note praise problem review suggestion
BeatmapsetDiscussionPost
Field Type Description beatmapset_discussion_id number created_at Timestamp deleted_at Timestamp? deleted_by_id number? id number last_editor_id number? message string system boolean updated_at Timestamp user_id number
BeatmapsetDiscussionVote
Field Type Description beatmapset_discussion_id number created_at Timestamp id number score number updated_at Timestamp user_id number
Build
Field Type created_at Timestamp display_version string id number update_stream UpdateStream? users number version string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes changelog_entries ChangelogEntry[] If the build has no changelog entries, a placeholder is generated. versions Versions
Versions
ChangelogEntry
Field Type category string created_at Timestamp? github_pull_request_id number? github_url string? id number? major boolean repository string? title string? type string url string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes github_user GithubUser If the changelog entry has no GitHub user, a placeholder is generated. message string? Entry message in Markdown format. Embedded HTML is allowed. message_html string? Entry message in HTML format.
ChatChannel
Represents an individual chat «channel» in the game.
Channel Types
Type Permission Check for Joining/Messaging PUBLIC PRIVATE is player in the allowed groups? (channel.allowed_groups) MULTIPLAYER is player currently in the mp game? SPECTATOR TEMPORARY deprecated PM see below (user_channels) GROUP is player in channel? (user_channels)
For PMs, two factors are taken into account:
ChatMessage
Represents an individual Message within a ChatChannel.
Field Type Description message_id number unique identifier for message sender_id number user_id of the sender channel_id number channel_id of where the message was sent timestamp string when the message was sent, ISO-8601 content string message content is_action boolean was this an action? i.e. /me dances sender UserCompact embedded UserCompact object to save additional api lookups
Comment
Represents an single comment.
Field Type Description commentable_id number ID of the object the comment is attached to commentable_type string type of object the comment is attached to created_at string ISO 8601 date deleted_at string? ISO 8601 date if the comment was deleted; null, otherwise edited_at string? ISO 8601 date if the comment was edited; null, otherwise edited_by_id number? user id of the user that edited the post; null, otherwise id number the ID of the comment legacy_name string? username displayed on legacy comments message string? markdown of the comment’s content message_html string? html version of the comment’s content parent_id number? ID of the comment’s parent pinned boolean Pin status of the comment replies_count number number of replies to the comment updated_at string ISO 8601 date user_id number user ID of the poster votes_count number number of votes
CommentBundle
Comments and related data.
Field Type Description commentable_meta CommentableMeta[] ID of the object the comment is attached to comments Comment[] Array of comments ordered according to sort ; cursor Cursor has_more boolean If there are more comments or replies available has_more_id number? included_comments Comment[] Related comments; e.g. parent comments and nested replies pinned_comments Comment[]? Pinned comments sort string one of the CommentSort types top_level_count number? Number of comments at the top level. Not returned for replies. total number? Total number of comments. Not retuned for replies. user_follow boolean is the current user watching the comment thread? user_votes number[] IDs of the comments in the bundle the current user has upvoted users UserCompact[] array of users related to the comments
CommentSort
Type Sort Fields new created_at (descending), id (descending) old created_at (ascending), id (ascending) top votes_count (descending), created_at (descending), id (descending)
Building cursor for comments listing
The returned response will be for comments after the specified sort fields.
For example, use last loaded comment for the fields value to load more comments. Also make sure to use same sort and parent_id values.
CommentableMeta
Metadata of the object that a comment is attached to.
Field Type Description id number the ID of the object title string display title type string the type of the object url string url of the object
CurrentUserAttributes
An object listing various related permissions and states for the current user, related to the object it is attached to.
BeatmapsetDiscussionPermissions
TODO: needs a better name.
Name Description can_destroy Can delete the discussion. can_reopen Can reopen the discussion. can_moderate_kudosu Can allow or deny kudosu. can_resolve Can resolve the discussion. vote_score Current vote given to the discussion.
ChatChannelUserAttributes
Name Type Description can_message boolean Can send messages to this channel. can_message_error string? Reason messages cannot be sent to this channel last_read_id number message_id of last message read.
Cursor
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.
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
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-07-06
2022-06-08
2021-10-28
2021-09-01
2021-08-11
2021-06-14
2021-06-09
2021-04-20
2021-02-25
2020-09-08
2020-08-28
2020-05-01
2020-02-18
2019-10-09
2019-07-18
Endpoint
Base URL
The base URL is: https://osu.ppy.sh/api/[version]/
API Versions
This is combined with the base endpoint to determine where requests should be sent.
Version Status v2 current (not yet public, consider unstable and expect breaking changes) v1 legacy api provided by the old site, will be deprecated soon
Authentication
Routes marked with the OAuth label require a valid OAuth2 token for access.
More information about applications you have registered and granted permissions to can be found here.
The API supports the following grant types:
Before you can use the osu!api, you will need to
Registering an OAuth application
Before you can get an OAuth token, you will need to register an OAuth application on your account settings page
To register an OAuth application you will need to provide the:
Name Description Application Name This is the name that will be visible to users of your application. The name of your application cannot be changed. Application Callback URL The URL in your application where users will be sent after authorization.
The Application Callback URL is required when for using Authorization Codes. This may be left blank if you are only using Client Credentials Grants.
Your new OAuth application will have a Client ID and Client Secret ; the Client Secret is like a password for your OAuth application, it should be kept private and do not share it with anyone else.
Authorization Code Grant
The flow to authorize users for your application is:
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:
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:
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.
Make sure to replace <> 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:
Name Description chat.write Allows sending chat messages on a user’s behalf. delegate Allows acting as the owner of a client; only available for Client Credentials Grant. forum.write Allows creating and editing forum posts on a user’s behalf. friends.read Allows reading of the user’s friend list. identify Allows reading of the public profile of the user ( /me ). public Allows reading of publicly available data on behalf of the user.
identify is the default scope for the Authorization Code Grant and always implicitly provided. The Client Credentials Grant does not currently have any default scopes.
Routes marked with lazer are intended for use by the osu!lazer client and not currently available for use with Authorization Code or Client Credentials grants.
Using the chat.write scope requires either
Managing OAuth applications
Your account settings page will show your registered OAuth applications, and all the OAuth applications you have granted permissions to.
Reset Client Secret
You can generate a new Client Secret by choosing to «Reset client secret», however, this will disable all access tokens issued for the application.
Beatmaps
Lookup Beatmap
Response format
Get a User Beatmap score
Return a User’s score on a Beatmap
Response Format
The position returned depends on the requested mode and mods.
Get a User Beatmap scores
Return a User’s scores on a Beatmap
Response Format
Get Beatmap scores
Returns the top scores for a beatmap
Response Format
Get Beatmap scores (temp)
Returns the top scores for a beatmap from newer client.
This is a temporary endpoint.
Response Format
Get Beatmaps
Returns list of beatmaps.
Response format
Field Type Description beatmaps BeatmapCompact[] Includes: beatmapset (with ratings), failtimes, max_combo.
Get Beatmap
Gets beatmap data for the specified beatmap ID.
Response format
Returns Beatmap object. Following attributes are included in the response object when applicable,
Attribute Notes beatmapset Includes ratings property. failtimes max_combo
Get Beatmap Attributes
Returns difficulty attributes of beatmap with specific mode and mods combination.
Response format
Beatmapset Discussions
Get Beatmapset Discussion Posts
Returns the posts of beatmapset discussions.
Response Format
Get Beatmapset Discussion Votes
Returns the votes given to beatmapset discussions.
Response Format
Get Beatmapset Discussions
Returns a list of beatmapset discussions.
Response Format
Changelog
Get Changelog Build
Returns details of the specified build.
Response Format
Get Changelog Listing
Returns a listing of update streams, builds, and changelog entries.
Response Format
Lookup Changelog Build
Returns details of the specified build.
Response Format
Create New PM
This endpoint allows you to create a new PM channel.
Response Format
Field Type new_channel_id channel_id of newly created ChatChannel presence array of ChatChannel message the sent ChatMessage
This endpoint will only allow the creation of PMs initially, group chat support will come later.
Get Updates
This endpoint returns new messages since the given message_id along with updated channel ‘presence’ data.
Response Format
Get Channel Messages
This endpoint returns the chat messages for a specific channel.
Response Format
Returns an array of ChatMessage
Send Message to Channel
This endpoint returns the chat messages for a specific channel.
Response Format
Join Channel
This endpoint allows you to join a public or multiplayer channel.
Response Format
Returns the joined ChatChannel.
Leave Channel
This endpoint allows you to leave a public channel.
Response Format
Mark Channel as Read
Response Format
Get Channel List
This endpoint returns a list of all joinable public channels.
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.
Response Format
Returns ChatChannel with recent_messages attribute. Note that in the case of PM s, 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.
Response Format
Field Type Description channel ChatChannel users UserCompact Users are only visible for PM channels.
Comments
Get Comments
Returns a list comments and their replies up to 2 levels deep.
Response Format
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.
Response Format
Get a Comment
Gets a comment and its replies up to 2 levels deep.
Response Format
Edit Comment
Edit an existing comment.
Response Format
Delete Comment
Deletes the specified comment.
Response Format
Add Comment vote
Upvotes a comment.
Response Format
Remove Comment vote
Un-upvotes a comment.
Response Format
Forum
Reply Topic
Create a post replying to the specified topic.
Response Format
ForumPost with body included.
Create Topic
Create a new topic.
Response Format
Get Topic and Posts
Get topic and its posts.
Response Format
Edit Topic
Edit topic. Only title can be edited through this endpoint.
Response Format
Edit Post
Edit specified forum post.
Response Format
ForumPost with body included.
Search
Searches users and wiki pages.
Response Format
SearchResult
Multiplayer
Get User High Score
Returns detail of highest score of specified user and the surrounding scores.
Response Format
Get Scores
Returns a list of scores for specified playlist item.
Response Format
Get a Score
Returns detail of specified score and the surrounding scores.
Response Format
Get News Listing
Returns a list of news posts and related metadata.
Response Format
Get News Post
Returns details of the specified news post.
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.
Response Format
Returns an object containing Notification and other related attributes.
Field Type has_more boolean whether or not there are more notifications notifications array of Notification unread_count total unread notifications notification_endpoint url to connect to websocket server
Mark Notifications as Read
This endpoint allows you to mark notifications read.
Response Format
OAuth Tokens
Revoke current token
Revokes currently authenticated token.
Ranking
Get Ranking
Gets the current ranking for the specified type and game mode.
Response Format
Get Spotlights
Gets the list of spotlights.
Response Format
Undocumented
/beatmaps//solo/scores
/beatmaps//solo/scores//beatmapsets/events
/beatmapsets//favourites
/chat/presence
/matches
/matches//rooms//rooms//users//rooms//users//rooms//leaderboard
/rooms//playlist//scores
/rooms//playlist//scores//reports
/rooms
/rooms//seasonal-backgrounds
/scores///download
/scores///beatmapsets/search//beatmapsets/lookup
/beatmapsets//friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
Similar to Get User but with authenticated user (token owner) as user id.
Response format
Additionally, statistics_rulesets is included, containing statistics for all rulesets.
Get User Kudosu
Returns kudosu history.
Response format
Get User Scores
This endpoint returns the scores of specified user.
Response format
Array of Score. Following attributes are included in the response object when applicable.
Get User Beatmaps
Returns the beatmaps of specified user.
Type Notes favourite graveyard loved most_played pending Previously unranked ranked Previously ranked_and_approved
Response format
Array of BeatmapPlaycount when type is most_played ; array of Beatmapset, otherwise.
Get User Recent Activity
Returns recent activity.
Response format
Get User
This endpoint returns the detail of specified user.
Response format
Returns User object. The following optional attributes on UserCompact are included:
Get Users
Returns list of users.
Response format
Field Type Description users UserCompact[] Includes: country, cover, groups, statistics_rulesets.
Get Wiki Page
The wiki article or image data.
Response Format
Notification Websocket
Connection
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:
Field Type Description event string See below
logout event
Server will disconnect session after sending this event so don’t try to reconnect.
Field Type Description event string logout
new event
New notification. See Notification object for notification types.
Field Type Description event string new data Notification
read event
Notification has been read.
Field Type Description event string read ids number[] id of Notifications which are read
Object Structures
Beatmap
Represent a beatmap. This extends BeatmapCompact with additional attributes.
Field Type Description accuracy float ar float beatmapset_id integer bpm float? convert boolean count_circles integer count_sliders integer count_spinners integer cs float deleted_at Timestamp? drain float hit_length integer is_scoreable boolean last_updated Timestamp mode_int integer passcount integer playcount integer ranked integer See Rank status for list of possible values. url string
BeatmapCompact
Represent a beatmap.
Field Type Description beatmapset_id integer difficulty_rating float id integer mode GameMode status string See Rank status for list of possible values. total_length integer user_id integer version string
Field Type Description beatmapset Beatmapset|BeatmapsetCompact|null Beatmapset for Beatmap object, BeatmapsetCompact for BeatmapCompact object. null if the beatmap doesn’t have associated beatmapset (e.g. deleted). checksum string? failtimes Failtimes max_combo integer
Failtimes
All fields are optional but there’s always at least one field returned.
Field Type Description exit integer[]? Array of length 100. fail integer[]? Array of length 100.
BeatmapDifficultyAttributes
Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.
Field Type max_combo integer star_rating float
Field Type aim_difficulty float approach_rate float flashlight_difficulty float overall_difficulty float slider_factor float speed_difficulty float
taiko
Field Type stamina_difficulty float rhythm_difficulty float colour_difficulty float approach_rate float great_hit_window float
fruits
mania
Field Type great_hit_window float score_multiplier float
BeatmapPlaycount
Represent the playcount of a beatmap.
Field Type Description beatmap_id number beatmap BeatmapCompact? beatmapset BeatmapsetCompact? count number
BeatmapScores
Field Type Description scores Score[] The list of top scores for the beatmap in descending order. userScore BeatmapUserScore? The score of the current user. This is not returned if the current user does not have a score. Note: will be moved to user_score in the future
BeatmapUserScore
Field Type Description position number The position of the score within the requested beatmap ranking. score Score The details of the score.
Beatmapset
Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.
Field Type Description availability.download_disabled boolean availability.more_information string? bpm float can_be_hyped boolean creator string Username of the mapper at the time of beatmapset creation. discussion_locked boolean hype.current integer hype.required integer is_scoreable boolean last_updated Timestamp legacy_thread_url string? nominations.current integer nominations.required integer ranked integer See Rank status for list of possible values. ranked_date Timestamp? source string storyboard boolean submitted_date Timestamp? tags string
The following attributes are always included as well:
Field has_favourited
BeatmapsetCompact
Represents a beatmapset.
Field Type Description artist string artist_unicode string covers Covers creator string favourite_count number id number nsfw boolean play_count number preview_url string source string status string title string title_unicode string user_id number video boolean
Those fields are optional.
Field Type Description beatmaps Beatmap[] converts current_user_attributes description discussions events genre has_favourited boolean language nominations ratings recent_favourites related_users user
Covers
Field Type cover string cover@2x string card string card@2x string list string list@2x string slimcover string slimcover@2x string
Rank status
The possible values are denoted either as integer or string.
Integer String -2 graveyard -1 wip 0 pending 1 ranked 2 approved 3 qualified 4 loved
BeatmapsetDiscussion
Represents a Beatmapset modding discussion.
Field Type Description beatmap BeatmapCompact? beatmap_id number? beatmapset BeatmapsetCompact? beatmapset_id number can_be_resolved boolean can_grant_kudosu boolean created_at Timestamp current_user_attributes CurrentUserAttributes deleted_at Timestamp? deleted_by_id number? id number kudosu_denied boolean last_post_at Timestamp message_type MessageType parent_id number? posts BeatmapsetDiscussionPost[]? resolved boolean starting_post BeatmapsetDiscussionPost? timestamp number? updated_at Timestamp user_id number
MessageType
Name Description hype mapper_note praise problem review suggestion
BeatmapsetDiscussionPost
Field Type Description beatmapset_discussion_id number created_at Timestamp deleted_at Timestamp? deleted_by_id number? id number last_editor_id number? message string system boolean updated_at Timestamp user_id number
BeatmapsetDiscussionVote
Field Type Description beatmapset_discussion_id number created_at Timestamp id number score number updated_at Timestamp user_id number
Build
Field Type created_at Timestamp display_version string id number update_stream UpdateStream? users number version string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes changelog_entries ChangelogEntry[] If the build has no changelog entries, a placeholder is generated. versions Versions
Versions
ChangelogEntry
Field Type category string created_at Timestamp? github_pull_request_id number? github_url string? id number? major boolean repository string? title string? type string url string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes github_user GithubUser If the changelog entry has no GitHub user, a placeholder is generated. message string? Entry message in Markdown format. Embedded HTML is allowed. message_html string? Entry message in HTML format.
ChatChannel
Represents an individual chat «channel» in the game.
Channel Types
Type Permission Check for Joining/Messaging PUBLIC PRIVATE is player in the allowed groups? (channel.allowed_groups) MULTIPLAYER is player currently in the mp game? SPECTATOR TEMPORARY deprecated PM see below (user_channels) GROUP is player in channel? (user_channels)
For PMs, two factors are taken into account:
ChatMessage
Represents an individual Message within a ChatChannel.
Field Type Description message_id number unique identifier for message sender_id number user_id of the sender channel_id number channel_id of where the message was sent timestamp string when the message was sent, ISO-8601 content string message content is_action boolean was this an action? i.e. /me dances sender UserCompact embedded UserCompact object to save additional api lookups
Comment
Represents an single comment.
Field Type Description commentable_id number ID of the object the comment is attached to commentable_type string type of object the comment is attached to created_at string ISO 8601 date deleted_at string? ISO 8601 date if the comment was deleted; null, otherwise edited_at string? ISO 8601 date if the comment was edited; null, otherwise edited_by_id number? user id of the user that edited the post; null, otherwise id number the ID of the comment legacy_name string? username displayed on legacy comments message string? markdown of the comment’s content message_html string? html version of the comment’s content parent_id number? ID of the comment’s parent pinned boolean Pin status of the comment replies_count number number of replies to the comment updated_at string ISO 8601 date user_id number user ID of the poster votes_count number number of votes
CommentBundle
Comments and related data.
Field Type Description commentable_meta CommentableMeta[] ID of the object the comment is attached to comments Comment[] Array of comments ordered according to sort ; cursor Cursor has_more boolean If there are more comments or replies available has_more_id number? included_comments Comment[] Related comments; e.g. parent comments and nested replies pinned_comments Comment[]? Pinned comments sort string one of the CommentSort types top_level_count number? Number of comments at the top level. Not returned for replies. total number? Total number of comments. Not retuned for replies. user_follow boolean is the current user watching the comment thread? user_votes number[] IDs of the comments in the bundle the current user has upvoted users UserCompact[] array of users related to the comments
CommentSort
Type Sort Fields new created_at (descending), id (descending) old created_at (ascending), id (ascending) top votes_count (descending), created_at (descending), id (descending)
Building cursor for comments listing
The returned response will be for comments after the specified sort fields.
For example, use last loaded comment for the fields value to load more comments. Also make sure to use same sort and parent_id values.
CommentableMeta
Metadata of the object that a comment is attached to.
Field Type Description id number the ID of the object title string display title type string the type of the object url string url of the object
CurrentUserAttributes
An object listing various related permissions and states for the current user, related to the object it is attached to.
BeatmapsetDiscussionPermissions
TODO: needs a better name.
Name Description can_destroy Can delete the discussion. can_reopen Can reopen the discussion. can_moderate_kudosu Can allow or deny kudosu. can_resolve Can resolve the discussion. vote_score Current vote given to the discussion.
ChatChannelUserAttributes
Name Type Description can_message boolean Can send messages to this channel. can_message_error string? Reason messages cannot be sent to this channel last_read_id number message_id of last message read.
Cursor
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.
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
osu!api open beta
Нет аккаунта?
osu!api open beta
I’ve had an API available for a while but until now it has been on a private on-request basis. In order to try and make developing third party services which expand and support osu!, I have added an API key setup and started to document the API.
Documentation will be expanded as I find time to do so! If anyone currently using the API is able to help expand the documentation then please do.
comentarinformal wrote:
Before I spam it with requests that might not exist, is there anything to get user’s information?
(Also, is there anything to login users from this page in other places?)
There is /api/get_user
Gonna write an entry with the information I have about it.
Is there a fair use limit? (e.g. no more than XX requests per day)
For get_user, I suppose there is a mode parameter for getting user information for Taiko, CtB and osu!mania? Or do I have to file an issue in GitHub? Nevermind, I found it, the parameter to add is called «m» I have edited the GitHub wiki.
Oh well. I have some questions:
Are only the beatmap and user endpoints available?
The parameter «since» in /get_beatmap how I need to pass the time on it? UTC or unix timestamp?
Do I need to pass the key on the wiki’s API too?
Edit: What the countX values mean? Number of beatmaps?
comentarinformal wrote:
Before I spam it with requests that might not exist, is there anything to get user’s information?
(Also, is there anything to login users from this page in other places?)
I guess I’ll update my userbar too when I find some time.
Damnae wrote:
I guess I’ll update my userbar too when I find some time.
I registered it for osu!userbar, but I also use it for my «Big ugly white signature», they are not on the same webserver, but it works fine
I belive only you and peppy can see the name you used, too.
(Yes I took my lazyness off, it was not that long to update ^^)
@Repflez: I tried using your API-powered signature and I get something weird.
Since I only aim for SS, I have 100% Accuracy all the time, and the Accuracy display is weird.
(I now know that despite having all-SS records, the note hit count for getting 50s and 100s are still counted all the time )
Winshley wrote:
@Repflez: I tried using your API-powered signature and I get something weird.
Since I only aim for SS, I have 100% Accuracy all the time, and the Accuracy display is weird.
(I now know that despite having all-SS records, the note hit count for getting 50s and 100s are still counted all the time )
So that’s what the CountX values mean. Thanks for that. I already went and changed the accuracy to show a centered «100% Accuracy» if it’s 100. Forget that. I ditched the bar on it and used the extra space for showing the PP.
(I love how the 300 count ended overlaping the border)
Repflez wrote:
So that’s what the CountX values mean. Thanks for that.
Yeah. At first I thought that there was something wrong with the API showing 50s and 100s despite having 100% Accuracy, until I actually calculated all 300s + 100s + 50s = «Total Hits» on our profile.
About the 300 overlap though, it does need some fix:
When you reached 10 millions of 300 hits, the last number is cut off. Cookiezi has 17 millions of 300 hits.
I’m not sure how the level bar breaking happens though. I was thinking that it probably because I don’t have any ranked score on osu!mania?
[Archived] getting osu! api token
Нет аккаунта?
[Archived] getting osu! api token
here is the website I am currently using this for https://osu-api-crap.minecreeper0913.repl.co
well since the project I am using is all python and not javascript I am using a new tab browser to just test it and so far the code I am using is
url = («https://osu.ppy.sh/oauth/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=%s» % (code))
the &code=%s is basically just grabbing the code that has been given back by oauth and using that as the url, when I am testing it though I am actually using my code
Never share your client secret, it’s secret for a reason. I would recommend resetting it ASAP.
Are you just typing that URL into your browser or are you actually sending it as a post request with whatever python code you have? Typing the URL into your browser won’t work.
The token endpoint takes the parameters in the body of the request, not as query parameters. You are also missing some parameters, like redirect_uri and grant_type.
If you are using python’s requests library, you can do something like this:
Might have some syntax errors because I wrote that from memory and didn’t check anything in an IDE or by running it.
You can try without specifying the content type in your headers, it might work without it. Very simply, the content type header describes what type of content or data is being sent. As far as I recall, the server is expecting that content type but I could be wrong.
now starting to realize that I might have done this a bit wrong, this is the first time I have used an API for something so everything I am doing is new to me.
So the first thing that is happening is that you press the login to link your osu API to the website, then it grabs your code and redirects you to the home website with the code in the url for example http://www.website.com/code=j9838r9y82g9438gh8243hg384hg, and it is supposed to use that, but when in testing it just returns favicon.ico, and I don’t know what that is or means so I might have to change my get request, another issue is but how would I make it get that auth code?
I don’t know anything about the project you are working on, so unfortunately I don’t think I can really answer any of the questions you’re asking.
I don’t know what you mean by a favicon being returned and I also don’t know what you are using the handle the backend of your site, so I can’t specifically tell you how to grab the code. Whatever you are using should have some way of getting query parameters from the URL.
Oauth2 is a very standardized and should be nearly the same everywhere that uses it. osu! is no exception. I would highly recommend looking up and reading about the authorization code flow that you are trying to use here. There should be a ton of resources and maybe a few code examples as well.
There might not be any videos specific to osu!’s API, but there are definitely Oauth2 tutorial videos and examples out there in probably every programming language, which is what you are dealing with right now.
For example, here is a video I found after a quick Google search that is using Python. I can’t fully comment on its quality since I just skimmed through it, but the general flow that the creator of the video goes over seems like it will at least cover how OAuth2 works in general, even if it’s not in the context of osu!’s API.
And even if you don’t really like reading, there are still some pretty good resources you can use that might help in addition to watching a video. Like this and this for example. Again, I’ve only skimmed through these, but they also seem to be pretty good.
here is the code I use:
NOTE I did not actually use SECRET as the secret I have it as SECRET because its secret
/rooms//leaderboard
/rooms//playlist//scores
/rooms//playlist//scores//reports
/rooms
/rooms//seasonal-backgrounds
/scores///download
/scores///beatmapsets/search//beatmapsets/lookup
/beatmapsets//friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
Similar to Get User but with authenticated user (token owner) as user id.
Response format
Additionally, statistics_rulesets is included, containing statistics for all rulesets.
Get User Kudosu
Returns kudosu history.
Response format
Get User Scores
This endpoint returns the scores of specified user.
Response format
Array of Score. Following attributes are included in the response object when applicable.
Get User Beatmaps
Returns the beatmaps of specified user.
Type Notes favourite graveyard loved most_played pending Previously unranked ranked Previously ranked_and_approved
Response format
Array of BeatmapPlaycount when type is most_played ; array of Beatmapset, otherwise.
Get User Recent Activity
Returns recent activity.
Response format
Get User
This endpoint returns the detail of specified user.
Response format
Returns User object. The following optional attributes on UserCompact are included:
Get Users
Returns list of users.
Response format
Field Type Description users UserCompact[] Includes: country, cover, groups, statistics_rulesets.
Get Wiki Page
The wiki article or image data.
Response Format
Notification Websocket
Connection
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:
Field Type Description event string See below
logout event
Server will disconnect session after sending this event so don’t try to reconnect.
Field Type Description event string logout
new event
New notification. See Notification object for notification types.
Field Type Description event string new data Notification
read event
Notification has been read.
Field Type Description event string read ids number[] id of Notifications which are read
Object Structures
Beatmap
Represent a beatmap. This extends BeatmapCompact with additional attributes.
Field Type Description accuracy float ar float beatmapset_id integer bpm float? convert boolean count_circles integer count_sliders integer count_spinners integer cs float deleted_at Timestamp? drain float hit_length integer is_scoreable boolean last_updated Timestamp mode_int integer passcount integer playcount integer ranked integer See Rank status for list of possible values. url string
BeatmapCompact
Represent a beatmap.
Field Type Description beatmapset_id integer difficulty_rating float id integer mode GameMode status string See Rank status for list of possible values. total_length integer user_id integer version string
Field Type Description beatmapset Beatmapset|BeatmapsetCompact|null Beatmapset for Beatmap object, BeatmapsetCompact for BeatmapCompact object. null if the beatmap doesn’t have associated beatmapset (e.g. deleted). checksum string? failtimes Failtimes max_combo integer
Failtimes
All fields are optional but there’s always at least one field returned.
Field Type Description exit integer[]? Array of length 100. fail integer[]? Array of length 100.
BeatmapDifficultyAttributes
Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.
Field Type max_combo integer star_rating float
Field Type aim_difficulty float approach_rate float flashlight_difficulty float overall_difficulty float slider_factor float speed_difficulty float
taiko
Field Type stamina_difficulty float rhythm_difficulty float colour_difficulty float approach_rate float great_hit_window float
fruits
mania
Field Type great_hit_window float score_multiplier float
BeatmapPlaycount
Represent the playcount of a beatmap.
Field Type Description beatmap_id number beatmap BeatmapCompact? beatmapset BeatmapsetCompact? count number
BeatmapScores
Field Type Description scores Score[] The list of top scores for the beatmap in descending order. userScore BeatmapUserScore? The score of the current user. This is not returned if the current user does not have a score. Note: will be moved to user_score in the future
BeatmapUserScore
Field Type Description position number The position of the score within the requested beatmap ranking. score Score The details of the score.
Beatmapset
Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.
Field Type Description availability.download_disabled boolean availability.more_information string? bpm float can_be_hyped boolean creator string Username of the mapper at the time of beatmapset creation. discussion_locked boolean hype.current integer hype.required integer is_scoreable boolean last_updated Timestamp legacy_thread_url string? nominations.current integer nominations.required integer ranked integer See Rank status for list of possible values. ranked_date Timestamp? source string storyboard boolean submitted_date Timestamp? tags string
The following attributes are always included as well:
Field has_favourited
BeatmapsetCompact
Represents a beatmapset.
Field Type Description artist string artist_unicode string covers Covers creator string favourite_count number id number nsfw boolean play_count number preview_url string source string status string title string title_unicode string user_id number video boolean
Those fields are optional.
Field Type Description beatmaps Beatmap[] converts current_user_attributes description discussions events genre has_favourited boolean language nominations ratings recent_favourites related_users user
Covers
Field Type cover string cover@2x string card string card@2x string list string list@2x string slimcover string slimcover@2x string
Rank status
The possible values are denoted either as integer or string.
Integer String -2 graveyard -1 wip 0 pending 1 ranked 2 approved 3 qualified 4 loved
BeatmapsetDiscussion
Represents a Beatmapset modding discussion.
Field Type Description beatmap BeatmapCompact? beatmap_id number? beatmapset BeatmapsetCompact? beatmapset_id number can_be_resolved boolean can_grant_kudosu boolean created_at Timestamp current_user_attributes CurrentUserAttributes deleted_at Timestamp? deleted_by_id number? id number kudosu_denied boolean last_post_at Timestamp message_type MessageType parent_id number? posts BeatmapsetDiscussionPost[]? resolved boolean starting_post BeatmapsetDiscussionPost? timestamp number? updated_at Timestamp user_id number
MessageType
Name Description hype mapper_note praise problem review suggestion
BeatmapsetDiscussionPost
Field Type Description beatmapset_discussion_id number created_at Timestamp deleted_at Timestamp? deleted_by_id number? id number last_editor_id number? message string system boolean updated_at Timestamp user_id number
BeatmapsetDiscussionVote
Field Type Description beatmapset_discussion_id number created_at Timestamp id number score number updated_at Timestamp user_id number
Build
Field Type created_at Timestamp display_version string id number update_stream UpdateStream? users number version string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes changelog_entries ChangelogEntry[] If the build has no changelog entries, a placeholder is generated. versions Versions
Versions
ChangelogEntry
Field Type category string created_at Timestamp? github_pull_request_id number? github_url string? id number? major boolean repository string? title string? type string url string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes github_user GithubUser If the changelog entry has no GitHub user, a placeholder is generated. message string? Entry message in Markdown format. Embedded HTML is allowed. message_html string? Entry message in HTML format.
ChatChannel
Represents an individual chat «channel» in the game.
Channel Types
Type Permission Check for Joining/Messaging PUBLIC PRIVATE is player in the allowed groups? (channel.allowed_groups) MULTIPLAYER is player currently in the mp game? SPECTATOR TEMPORARY deprecated PM see below (user_channels) GROUP is player in channel? (user_channels)
For PMs, two factors are taken into account:
ChatMessage
Represents an individual Message within a ChatChannel.
Field Type Description message_id number unique identifier for message sender_id number user_id of the sender channel_id number channel_id of where the message was sent timestamp string when the message was sent, ISO-8601 content string message content is_action boolean was this an action? i.e. /me dances sender UserCompact embedded UserCompact object to save additional api lookups
Comment
Represents an single comment.
Field Type Description commentable_id number ID of the object the comment is attached to commentable_type string type of object the comment is attached to created_at string ISO 8601 date deleted_at string? ISO 8601 date if the comment was deleted; null, otherwise edited_at string? ISO 8601 date if the comment was edited; null, otherwise edited_by_id number? user id of the user that edited the post; null, otherwise id number the ID of the comment legacy_name string? username displayed on legacy comments message string? markdown of the comment’s content message_html string? html version of the comment’s content parent_id number? ID of the comment’s parent pinned boolean Pin status of the comment replies_count number number of replies to the comment updated_at string ISO 8601 date user_id number user ID of the poster votes_count number number of votes
CommentBundle
Comments and related data.
Field Type Description commentable_meta CommentableMeta[] ID of the object the comment is attached to comments Comment[] Array of comments ordered according to sort ; cursor Cursor has_more boolean If there are more comments or replies available has_more_id number? included_comments Comment[] Related comments; e.g. parent comments and nested replies pinned_comments Comment[]? Pinned comments sort string one of the CommentSort types top_level_count number? Number of comments at the top level. Not returned for replies. total number? Total number of comments. Not retuned for replies. user_follow boolean is the current user watching the comment thread? user_votes number[] IDs of the comments in the bundle the current user has upvoted users UserCompact[] array of users related to the comments
CommentSort
Type Sort Fields new created_at (descending), id (descending) old created_at (ascending), id (ascending) top votes_count (descending), created_at (descending), id (descending)
Building cursor for comments listing
The returned response will be for comments after the specified sort fields.
For example, use last loaded comment for the fields value to load more comments. Also make sure to use same sort and parent_id values.
CommentableMeta
Metadata of the object that a comment is attached to.
Field Type Description id number the ID of the object title string display title type string the type of the object url string url of the object
CurrentUserAttributes
An object listing various related permissions and states for the current user, related to the object it is attached to.
BeatmapsetDiscussionPermissions
TODO: needs a better name.
Name Description can_destroy Can delete the discussion. can_reopen Can reopen the discussion. can_moderate_kudosu Can allow or deny kudosu. can_resolve Can resolve the discussion. vote_score Current vote given to the discussion.
ChatChannelUserAttributes
Name Type Description can_message boolean Can send messages to this channel. can_message_error string? Reason messages cannot be sent to this channel last_read_id number message_id of last message read.
Cursor
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.
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
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-07-06
2022-06-08
2021-10-28
2021-09-01
2021-08-11
2021-06-14
2021-06-09
2021-04-20
2021-02-25
2020-09-08
2020-08-28
2020-05-01
2020-02-18
2019-10-09
2019-07-18
Endpoint
Base URL
The base URL is: https://osu.ppy.sh/api/[version]/
API Versions
This is combined with the base endpoint to determine where requests should be sent.
Version Status v2 current (not yet public, consider unstable and expect breaking changes) v1 legacy api provided by the old site, will be deprecated soon
Authentication
Routes marked with the OAuth label require a valid OAuth2 token for access.
More information about applications you have registered and granted permissions to can be found here.
The API supports the following grant types:
Before you can use the osu!api, you will need to
Registering an OAuth application
Before you can get an OAuth token, you will need to register an OAuth application on your account settings page
To register an OAuth application you will need to provide the:
Name Description Application Name This is the name that will be visible to users of your application. The name of your application cannot be changed. Application Callback URL The URL in your application where users will be sent after authorization.
The Application Callback URL is required when for using Authorization Codes. This may be left blank if you are only using Client Credentials Grants.
Your new OAuth application will have a Client ID and Client Secret ; the Client Secret is like a password for your OAuth application, it should be kept private and do not share it with anyone else.
Authorization Code Grant
The flow to authorize users for your application is:
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:
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:
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.
Make sure to replace <> 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:
Name Description chat.write Allows sending chat messages on a user’s behalf. delegate Allows acting as the owner of a client; only available for Client Credentials Grant. forum.write Allows creating and editing forum posts on a user’s behalf. friends.read Allows reading of the user’s friend list. identify Allows reading of the public profile of the user ( /me ). public Allows reading of publicly available data on behalf of the user.
identify is the default scope for the Authorization Code Grant and always implicitly provided. The Client Credentials Grant does not currently have any default scopes.
Routes marked with lazer are intended for use by the osu!lazer client and not currently available for use with Authorization Code or Client Credentials grants.
Using the chat.write scope requires either
Managing OAuth applications
Your account settings page will show your registered OAuth applications, and all the OAuth applications you have granted permissions to.
Reset Client Secret
You can generate a new Client Secret by choosing to «Reset client secret», however, this will disable all access tokens issued for the application.
Beatmaps
Lookup Beatmap
Response format
Get a User Beatmap score
Return a User’s score on a Beatmap
Response Format
The position returned depends on the requested mode and mods.
Get a User Beatmap scores
Return a User’s scores on a Beatmap
Response Format
Get Beatmap scores
Returns the top scores for a beatmap
Response Format
Get Beatmap scores (temp)
Returns the top scores for a beatmap from newer client.
This is a temporary endpoint.
Response Format
Get Beatmaps
Returns list of beatmaps.
Response format
Field Type Description beatmaps BeatmapCompact[] Includes: beatmapset (with ratings), failtimes, max_combo.
Get Beatmap
Gets beatmap data for the specified beatmap ID.
Response format
Returns Beatmap object. Following attributes are included in the response object when applicable,
Attribute Notes beatmapset Includes ratings property. failtimes max_combo
Get Beatmap Attributes
Returns difficulty attributes of beatmap with specific mode and mods combination.
Response format
Beatmapset Discussions
Get Beatmapset Discussion Posts
Returns the posts of beatmapset discussions.
Response Format
Get Beatmapset Discussion Votes
Returns the votes given to beatmapset discussions.
Response Format
Get Beatmapset Discussions
Returns a list of beatmapset discussions.
Response Format
Changelog
Get Changelog Build
Returns details of the specified build.
Response Format
Get Changelog Listing
Returns a listing of update streams, builds, and changelog entries.
Response Format
Lookup Changelog Build
Returns details of the specified build.
Response Format
Create New PM
This endpoint allows you to create a new PM channel.
Response Format
Field Type new_channel_id channel_id of newly created ChatChannel presence array of ChatChannel message the sent ChatMessage
This endpoint will only allow the creation of PMs initially, group chat support will come later.
Get Updates
This endpoint returns new messages since the given message_id along with updated channel ‘presence’ data.
Response Format
Get Channel Messages
This endpoint returns the chat messages for a specific channel.
Response Format
Returns an array of ChatMessage
Send Message to Channel
This endpoint returns the chat messages for a specific channel.
Response Format
Join Channel
This endpoint allows you to join a public or multiplayer channel.
Response Format
Returns the joined ChatChannel.
Leave Channel
This endpoint allows you to leave a public channel.
Response Format
Mark Channel as Read
Response Format
Get Channel List
This endpoint returns a list of all joinable public channels.
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.
Response Format
Returns ChatChannel with recent_messages attribute. Note that in the case of PM s, 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.
Response Format
Field Type Description channel ChatChannel users UserCompact Users are only visible for PM channels.
Comments
Get Comments
Returns a list comments and their replies up to 2 levels deep.
Response Format
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.
Response Format
Get a Comment
Gets a comment and its replies up to 2 levels deep.
Response Format
Edit Comment
Edit an existing comment.
Response Format
Delete Comment
Deletes the specified comment.
Response Format
Add Comment vote
Upvotes a comment.
Response Format
Remove Comment vote
Un-upvotes a comment.
Response Format
Forum
Reply Topic
Create a post replying to the specified topic.
Response Format
ForumPost with body included.
Create Topic
Create a new topic.
Response Format
Get Topic and Posts
Get topic and its posts.
Response Format
Edit Topic
Edit topic. Only title can be edited through this endpoint.
Response Format
Edit Post
Edit specified forum post.
Response Format
ForumPost with body included.
Search
Searches users and wiki pages.
Response Format
SearchResult
Multiplayer
Get User High Score
Returns detail of highest score of specified user and the surrounding scores.
Response Format
Get Scores
Returns a list of scores for specified playlist item.
Response Format
Get a Score
Returns detail of specified score and the surrounding scores.
Response Format
Get News Listing
Returns a list of news posts and related metadata.
Response Format
Get News Post
Returns details of the specified news post.
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.
Response Format
Returns an object containing Notification and other related attributes.
Field Type has_more boolean whether or not there are more notifications notifications array of Notification unread_count total unread notifications notification_endpoint url to connect to websocket server
Mark Notifications as Read
This endpoint allows you to mark notifications read.
Response Format
OAuth Tokens
Revoke current token
Revokes currently authenticated token.
Ranking
Get Ranking
Gets the current ranking for the specified type and game mode.
Response Format
Get Spotlights
Gets the list of spotlights.
Response Format
Undocumented
/beatmaps//solo/scores
/beatmaps//solo/scores//beatmapsets/events
/beatmapsets//favourites
/chat/presence
/matches
/matches//rooms//rooms//users//rooms//users//rooms//leaderboard
/rooms//playlist//scores
/rooms//playlist//scores//reports
/rooms
/rooms//seasonal-backgrounds
/scores///download
/scores///beatmapsets/search//beatmapsets/lookup
/beatmapsets//friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
Similar to Get User but with authenticated user (token owner) as user id.
Response format
Additionally, statistics_rulesets is included, containing statistics for all rulesets.
Get User Kudosu
Returns kudosu history.
Response format
Get User Scores
This endpoint returns the scores of specified user.
Response format
Array of Score. Following attributes are included in the response object when applicable.
Get User Beatmaps
Returns the beatmaps of specified user.
Type Notes favourite graveyard loved most_played pending Previously unranked ranked Previously ranked_and_approved
Response format
Array of BeatmapPlaycount when type is most_played ; array of Beatmapset, otherwise.
Get User Recent Activity
Returns recent activity.
Response format
Get User
This endpoint returns the detail of specified user.
Response format
Returns User object. The following optional attributes on UserCompact are included:
Get Users
Returns list of users.
Response format
Field Type Description users UserCompact[] Includes: country, cover, groups, statistics_rulesets.
Get Wiki Page
The wiki article or image data.
Response Format
Notification Websocket
Connection
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:
Field Type Description event string See below
logout event
Server will disconnect session after sending this event so don’t try to reconnect.
Field Type Description event string logout
new event
New notification. See Notification object for notification types.
Field Type Description event string new data Notification
read event
Notification has been read.
Field Type Description event string read ids number[] id of Notifications which are read
Object Structures
Beatmap
Represent a beatmap. This extends BeatmapCompact with additional attributes.
Field Type Description accuracy float ar float beatmapset_id integer bpm float? convert boolean count_circles integer count_sliders integer count_spinners integer cs float deleted_at Timestamp? drain float hit_length integer is_scoreable boolean last_updated Timestamp mode_int integer passcount integer playcount integer ranked integer See Rank status for list of possible values. url string
BeatmapCompact
Represent a beatmap.
Field Type Description beatmapset_id integer difficulty_rating float id integer mode GameMode status string See Rank status for list of possible values. total_length integer user_id integer version string
Field Type Description beatmapset Beatmapset|BeatmapsetCompact|null Beatmapset for Beatmap object, BeatmapsetCompact for BeatmapCompact object. null if the beatmap doesn’t have associated beatmapset (e.g. deleted). checksum string? failtimes Failtimes max_combo integer
Failtimes
All fields are optional but there’s always at least one field returned.
Field Type Description exit integer[]? Array of length 100. fail integer[]? Array of length 100.
BeatmapDifficultyAttributes
Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.
Field Type max_combo integer star_rating float
Field Type aim_difficulty float approach_rate float flashlight_difficulty float overall_difficulty float slider_factor float speed_difficulty float
taiko
Field Type stamina_difficulty float rhythm_difficulty float colour_difficulty float approach_rate float great_hit_window float
fruits
mania
Field Type great_hit_window float score_multiplier float
BeatmapPlaycount
Represent the playcount of a beatmap.
Field Type Description beatmap_id number beatmap BeatmapCompact? beatmapset BeatmapsetCompact? count number
BeatmapScores
Field Type Description scores Score[] The list of top scores for the beatmap in descending order. userScore BeatmapUserScore? The score of the current user. This is not returned if the current user does not have a score. Note: will be moved to user_score in the future
BeatmapUserScore
Field Type Description position number The position of the score within the requested beatmap ranking. score Score The details of the score.
Beatmapset
Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.
Field Type Description availability.download_disabled boolean availability.more_information string? bpm float can_be_hyped boolean creator string Username of the mapper at the time of beatmapset creation. discussion_locked boolean hype.current integer hype.required integer is_scoreable boolean last_updated Timestamp legacy_thread_url string? nominations.current integer nominations.required integer ranked integer See Rank status for list of possible values. ranked_date Timestamp? source string storyboard boolean submitted_date Timestamp? tags string
The following attributes are always included as well:
Field has_favourited
BeatmapsetCompact
Represents a beatmapset.
Field Type Description artist string artist_unicode string covers Covers creator string favourite_count number id number nsfw boolean play_count number preview_url string source string status string title string title_unicode string user_id number video boolean
Those fields are optional.
Field Type Description beatmaps Beatmap[] converts current_user_attributes description discussions events genre has_favourited boolean language nominations ratings recent_favourites related_users user
Covers
Field Type cover string cover@2x string card string card@2x string list string list@2x string slimcover string slimcover@2x string
Rank status
The possible values are denoted either as integer or string.
Integer String -2 graveyard -1 wip 0 pending 1 ranked 2 approved 3 qualified 4 loved
BeatmapsetDiscussion
Represents a Beatmapset modding discussion.
Field Type Description beatmap BeatmapCompact? beatmap_id number? beatmapset BeatmapsetCompact? beatmapset_id number can_be_resolved boolean can_grant_kudosu boolean created_at Timestamp current_user_attributes CurrentUserAttributes deleted_at Timestamp? deleted_by_id number? id number kudosu_denied boolean last_post_at Timestamp message_type MessageType parent_id number? posts BeatmapsetDiscussionPost[]? resolved boolean starting_post BeatmapsetDiscussionPost? timestamp number? updated_at Timestamp user_id number
MessageType
Name Description hype mapper_note praise problem review suggestion
BeatmapsetDiscussionPost
Field Type Description beatmapset_discussion_id number created_at Timestamp deleted_at Timestamp? deleted_by_id number? id number last_editor_id number? message string system boolean updated_at Timestamp user_id number
BeatmapsetDiscussionVote
Field Type Description beatmapset_discussion_id number created_at Timestamp id number score number updated_at Timestamp user_id number
Build
Field Type created_at Timestamp display_version string id number update_stream UpdateStream? users number version string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes changelog_entries ChangelogEntry[] If the build has no changelog entries, a placeholder is generated. versions Versions
Versions
ChangelogEntry
Field Type category string created_at Timestamp? github_pull_request_id number? github_url string? id number? major boolean repository string? title string? type string url string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes github_user GithubUser If the changelog entry has no GitHub user, a placeholder is generated. message string? Entry message in Markdown format. Embedded HTML is allowed. message_html string? Entry message in HTML format.
ChatChannel
Represents an individual chat «channel» in the game.
Channel Types
Type Permission Check for Joining/Messaging PUBLIC PRIVATE is player in the allowed groups? (channel.allowed_groups) MULTIPLAYER is player currently in the mp game? SPECTATOR TEMPORARY deprecated PM see below (user_channels) GROUP is player in channel? (user_channels)
For PMs, two factors are taken into account:
ChatMessage
Represents an individual Message within a ChatChannel.
Field Type Description message_id number unique identifier for message sender_id number user_id of the sender channel_id number channel_id of where the message was sent timestamp string when the message was sent, ISO-8601 content string message content is_action boolean was this an action? i.e. /me dances sender UserCompact embedded UserCompact object to save additional api lookups
Comment
Represents an single comment.
Field Type Description commentable_id number ID of the object the comment is attached to commentable_type string type of object the comment is attached to created_at string ISO 8601 date deleted_at string? ISO 8601 date if the comment was deleted; null, otherwise edited_at string? ISO 8601 date if the comment was edited; null, otherwise edited_by_id number? user id of the user that edited the post; null, otherwise id number the ID of the comment legacy_name string? username displayed on legacy comments message string? markdown of the comment’s content message_html string? html version of the comment’s content parent_id number? ID of the comment’s parent pinned boolean Pin status of the comment replies_count number number of replies to the comment updated_at string ISO 8601 date user_id number user ID of the poster votes_count number number of votes
CommentBundle
Comments and related data.
Field Type Description commentable_meta CommentableMeta[] ID of the object the comment is attached to comments Comment[] Array of comments ordered according to sort ; cursor Cursor has_more boolean If there are more comments or replies available has_more_id number? included_comments Comment[] Related comments; e.g. parent comments and nested replies pinned_comments Comment[]? Pinned comments sort string one of the CommentSort types top_level_count number? Number of comments at the top level. Not returned for replies. total number? Total number of comments. Not retuned for replies. user_follow boolean is the current user watching the comment thread? user_votes number[] IDs of the comments in the bundle the current user has upvoted users UserCompact[] array of users related to the comments
CommentSort
Type Sort Fields new created_at (descending), id (descending) old created_at (ascending), id (ascending) top votes_count (descending), created_at (descending), id (descending)
Building cursor for comments listing
The returned response will be for comments after the specified sort fields.
For example, use last loaded comment for the fields value to load more comments. Also make sure to use same sort and parent_id values.
CommentableMeta
Metadata of the object that a comment is attached to.
Field Type Description id number the ID of the object title string display title type string the type of the object url string url of the object
CurrentUserAttributes
An object listing various related permissions and states for the current user, related to the object it is attached to.
BeatmapsetDiscussionPermissions
TODO: needs a better name.
Name Description can_destroy Can delete the discussion. can_reopen Can reopen the discussion. can_moderate_kudosu Can allow or deny kudosu. can_resolve Can resolve the discussion. vote_score Current vote given to the discussion.
ChatChannelUserAttributes
Name Type Description can_message boolean Can send messages to this channel. can_message_error string? Reason messages cannot be sent to this channel last_read_id number message_id of last message read.
Cursor
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.
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
osu!api open beta
Нет аккаунта?
osu!api open beta
I’ve had an API available for a while but until now it has been on a private on-request basis. In order to try and make developing third party services which expand and support osu!, I have added an API key setup and started to document the API.
Documentation will be expanded as I find time to do so! If anyone currently using the API is able to help expand the documentation then please do.
comentarinformal wrote:
Before I spam it with requests that might not exist, is there anything to get user’s information?
(Also, is there anything to login users from this page in other places?)
There is /api/get_user
Gonna write an entry with the information I have about it.
Is there a fair use limit? (e.g. no more than XX requests per day)
For get_user, I suppose there is a mode parameter for getting user information for Taiko, CtB and osu!mania? Or do I have to file an issue in GitHub? Nevermind, I found it, the parameter to add is called «m» I have edited the GitHub wiki.
Oh well. I have some questions:
Are only the beatmap and user endpoints available?
The parameter «since» in /get_beatmap how I need to pass the time on it? UTC or unix timestamp?
Do I need to pass the key on the wiki’s API too?
Edit: What the countX values mean? Number of beatmaps?
comentarinformal wrote:
Before I spam it with requests that might not exist, is there anything to get user’s information?
(Also, is there anything to login users from this page in other places?)
I guess I’ll update my userbar too when I find some time.
Damnae wrote:
I guess I’ll update my userbar too when I find some time.
I registered it for osu!userbar, but I also use it for my «Big ugly white signature», they are not on the same webserver, but it works fine
I belive only you and peppy can see the name you used, too.
(Yes I took my lazyness off, it was not that long to update ^^)
@Repflez: I tried using your API-powered signature and I get something weird.
Since I only aim for SS, I have 100% Accuracy all the time, and the Accuracy display is weird.
(I now know that despite having all-SS records, the note hit count for getting 50s and 100s are still counted all the time )
Winshley wrote:
@Repflez: I tried using your API-powered signature and I get something weird.
Since I only aim for SS, I have 100% Accuracy all the time, and the Accuracy display is weird.
(I now know that despite having all-SS records, the note hit count for getting 50s and 100s are still counted all the time )
So that’s what the CountX values mean. Thanks for that. I already went and changed the accuracy to show a centered «100% Accuracy» if it’s 100. Forget that. I ditched the bar on it and used the extra space for showing the PP.
(I love how the 300 count ended overlaping the border)
Repflez wrote:
So that’s what the CountX values mean. Thanks for that.
Yeah. At first I thought that there was something wrong with the API showing 50s and 100s despite having 100% Accuracy, until I actually calculated all 300s + 100s + 50s = «Total Hits» on our profile.
About the 300 overlap though, it does need some fix:
When you reached 10 millions of 300 hits, the last number is cut off. Cookiezi has 17 millions of 300 hits.
I’m not sure how the level bar breaking happens though. I was thinking that it probably because I don’t have any ranked score on osu!mania?
[Archived] getting osu! api token
Нет аккаунта?
[Archived] getting osu! api token
here is the website I am currently using this for https://osu-api-crap.minecreeper0913.repl.co
well since the project I am using is all python and not javascript I am using a new tab browser to just test it and so far the code I am using is
url = («https://osu.ppy.sh/oauth/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=%s» % (code))
the &code=%s is basically just grabbing the code that has been given back by oauth and using that as the url, when I am testing it though I am actually using my code
Never share your client secret, it’s secret for a reason. I would recommend resetting it ASAP.
Are you just typing that URL into your browser or are you actually sending it as a post request with whatever python code you have? Typing the URL into your browser won’t work.
The token endpoint takes the parameters in the body of the request, not as query parameters. You are also missing some parameters, like redirect_uri and grant_type.
If you are using python’s requests library, you can do something like this:
Might have some syntax errors because I wrote that from memory and didn’t check anything in an IDE or by running it.
You can try without specifying the content type in your headers, it might work without it. Very simply, the content type header describes what type of content or data is being sent. As far as I recall, the server is expecting that content type but I could be wrong.
now starting to realize that I might have done this a bit wrong, this is the first time I have used an API for something so everything I am doing is new to me.
So the first thing that is happening is that you press the login to link your osu API to the website, then it grabs your code and redirects you to the home website with the code in the url for example http://www.website.com/code=j9838r9y82g9438gh8243hg384hg, and it is supposed to use that, but when in testing it just returns favicon.ico, and I don’t know what that is or means so I might have to change my get request, another issue is but how would I make it get that auth code?
I don’t know anything about the project you are working on, so unfortunately I don’t think I can really answer any of the questions you’re asking.
I don’t know what you mean by a favicon being returned and I also don’t know what you are using the handle the backend of your site, so I can’t specifically tell you how to grab the code. Whatever you are using should have some way of getting query parameters from the URL.
Oauth2 is a very standardized and should be nearly the same everywhere that uses it. osu! is no exception. I would highly recommend looking up and reading about the authorization code flow that you are trying to use here. There should be a ton of resources and maybe a few code examples as well.
There might not be any videos specific to osu!’s API, but there are definitely Oauth2 tutorial videos and examples out there in probably every programming language, which is what you are dealing with right now.
For example, here is a video I found after a quick Google search that is using Python. I can’t fully comment on its quality since I just skimmed through it, but the general flow that the creator of the video goes over seems like it will at least cover how OAuth2 works in general, even if it’s not in the context of osu!’s API.
And even if you don’t really like reading, there are still some pretty good resources you can use that might help in addition to watching a video. Like this and this for example. Again, I’ve only skimmed through these, but they also seem to be pretty good.
here is the code I use:
NOTE I did not actually use SECRET as the secret I have it as SECRET because its secret
/reports
/rooms
/rooms//seasonal-backgrounds
/scores///download
/scores///beatmapsets/search//beatmapsets/lookup
/beatmapsets//friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
Similar to Get User but with authenticated user (token owner) as user id.
Response format
Additionally, statistics_rulesets is included, containing statistics for all rulesets.
Get User Kudosu
Returns kudosu history.
Response format
Get User Scores
This endpoint returns the scores of specified user.
Response format
Array of Score. Following attributes are included in the response object when applicable.
Get User Beatmaps
Returns the beatmaps of specified user.
Type Notes favourite graveyard loved most_played pending Previously unranked ranked Previously ranked_and_approved
Response format
Array of BeatmapPlaycount when type is most_played ; array of Beatmapset, otherwise.
Get User Recent Activity
Returns recent activity.
Response format
Get User
This endpoint returns the detail of specified user.
Response format
Returns User object. The following optional attributes on UserCompact are included:
Get Users
Returns list of users.
Response format
Field Type Description users UserCompact[] Includes: country, cover, groups, statistics_rulesets.
Get Wiki Page
The wiki article or image data.
Response Format
Notification Websocket
Connection
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:
Field Type Description event string See below
logout event
Server will disconnect session after sending this event so don’t try to reconnect.
Field Type Description event string logout
new event
New notification. See Notification object for notification types.
Field Type Description event string new data Notification
read event
Notification has been read.
Field Type Description event string read ids number[] id of Notifications which are read
Object Structures
Beatmap
Represent a beatmap. This extends BeatmapCompact with additional attributes.
Field Type Description accuracy float ar float beatmapset_id integer bpm float? convert boolean count_circles integer count_sliders integer count_spinners integer cs float deleted_at Timestamp? drain float hit_length integer is_scoreable boolean last_updated Timestamp mode_int integer passcount integer playcount integer ranked integer See Rank status for list of possible values. url string
BeatmapCompact
Represent a beatmap.
Field Type Description beatmapset_id integer difficulty_rating float id integer mode GameMode status string See Rank status for list of possible values. total_length integer user_id integer version string
Field Type Description beatmapset Beatmapset|BeatmapsetCompact|null Beatmapset for Beatmap object, BeatmapsetCompact for BeatmapCompact object. null if the beatmap doesn’t have associated beatmapset (e.g. deleted). checksum string? failtimes Failtimes max_combo integer
Failtimes
All fields are optional but there’s always at least one field returned.
Field Type Description exit integer[]? Array of length 100. fail integer[]? Array of length 100.
BeatmapDifficultyAttributes
Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.
Field Type max_combo integer star_rating float
Field Type aim_difficulty float approach_rate float flashlight_difficulty float overall_difficulty float slider_factor float speed_difficulty float
taiko
Field Type stamina_difficulty float rhythm_difficulty float colour_difficulty float approach_rate float great_hit_window float
fruits
mania
Field Type great_hit_window float score_multiplier float
BeatmapPlaycount
Represent the playcount of a beatmap.
Field Type Description beatmap_id number beatmap BeatmapCompact? beatmapset BeatmapsetCompact? count number
BeatmapScores
Field Type Description scores Score[] The list of top scores for the beatmap in descending order. userScore BeatmapUserScore? The score of the current user. This is not returned if the current user does not have a score. Note: will be moved to user_score in the future
BeatmapUserScore
Field Type Description position number The position of the score within the requested beatmap ranking. score Score The details of the score.
Beatmapset
Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.
Field Type Description availability.download_disabled boolean availability.more_information string? bpm float can_be_hyped boolean creator string Username of the mapper at the time of beatmapset creation. discussion_locked boolean hype.current integer hype.required integer is_scoreable boolean last_updated Timestamp legacy_thread_url string? nominations.current integer nominations.required integer ranked integer See Rank status for list of possible values. ranked_date Timestamp? source string storyboard boolean submitted_date Timestamp? tags string
The following attributes are always included as well:
Field has_favourited
BeatmapsetCompact
Represents a beatmapset.
Field Type Description artist string artist_unicode string covers Covers creator string favourite_count number id number nsfw boolean play_count number preview_url string source string status string title string title_unicode string user_id number video boolean
Those fields are optional.
Field Type Description beatmaps Beatmap[] converts current_user_attributes description discussions events genre has_favourited boolean language nominations ratings recent_favourites related_users user
Covers
Field Type cover string cover@2x string card string card@2x string list string list@2x string slimcover string slimcover@2x string
Rank status
The possible values are denoted either as integer or string.
Integer String -2 graveyard -1 wip 0 pending 1 ranked 2 approved 3 qualified 4 loved
BeatmapsetDiscussion
Represents a Beatmapset modding discussion.
Field Type Description beatmap BeatmapCompact? beatmap_id number? beatmapset BeatmapsetCompact? beatmapset_id number can_be_resolved boolean can_grant_kudosu boolean created_at Timestamp current_user_attributes CurrentUserAttributes deleted_at Timestamp? deleted_by_id number? id number kudosu_denied boolean last_post_at Timestamp message_type MessageType parent_id number? posts BeatmapsetDiscussionPost[]? resolved boolean starting_post BeatmapsetDiscussionPost? timestamp number? updated_at Timestamp user_id number
MessageType
Name Description hype mapper_note praise problem review suggestion
BeatmapsetDiscussionPost
Field Type Description beatmapset_discussion_id number created_at Timestamp deleted_at Timestamp? deleted_by_id number? id number last_editor_id number? message string system boolean updated_at Timestamp user_id number
BeatmapsetDiscussionVote
Field Type Description beatmapset_discussion_id number created_at Timestamp id number score number updated_at Timestamp user_id number
Build
Field Type created_at Timestamp display_version string id number update_stream UpdateStream? users number version string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes changelog_entries ChangelogEntry[] If the build has no changelog entries, a placeholder is generated. versions Versions
Versions
ChangelogEntry
Field Type category string created_at Timestamp? github_pull_request_id number? github_url string? id number? major boolean repository string? title string? type string url string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes github_user GithubUser If the changelog entry has no GitHub user, a placeholder is generated. message string? Entry message in Markdown format. Embedded HTML is allowed. message_html string? Entry message in HTML format.
ChatChannel
Represents an individual chat «channel» in the game.
Channel Types
Type Permission Check for Joining/Messaging PUBLIC PRIVATE is player in the allowed groups? (channel.allowed_groups) MULTIPLAYER is player currently in the mp game? SPECTATOR TEMPORARY deprecated PM see below (user_channels) GROUP is player in channel? (user_channels)
For PMs, two factors are taken into account:
ChatMessage
Represents an individual Message within a ChatChannel.
Field Type Description message_id number unique identifier for message sender_id number user_id of the sender channel_id number channel_id of where the message was sent timestamp string when the message was sent, ISO-8601 content string message content is_action boolean was this an action? i.e. /me dances sender UserCompact embedded UserCompact object to save additional api lookups
Comment
Represents an single comment.
Field Type Description commentable_id number ID of the object the comment is attached to commentable_type string type of object the comment is attached to created_at string ISO 8601 date deleted_at string? ISO 8601 date if the comment was deleted; null, otherwise edited_at string? ISO 8601 date if the comment was edited; null, otherwise edited_by_id number? user id of the user that edited the post; null, otherwise id number the ID of the comment legacy_name string? username displayed on legacy comments message string? markdown of the comment’s content message_html string? html version of the comment’s content parent_id number? ID of the comment’s parent pinned boolean Pin status of the comment replies_count number number of replies to the comment updated_at string ISO 8601 date user_id number user ID of the poster votes_count number number of votes
CommentBundle
Comments and related data.
Field Type Description commentable_meta CommentableMeta[] ID of the object the comment is attached to comments Comment[] Array of comments ordered according to sort ; cursor Cursor has_more boolean If there are more comments or replies available has_more_id number? included_comments Comment[] Related comments; e.g. parent comments and nested replies pinned_comments Comment[]? Pinned comments sort string one of the CommentSort types top_level_count number? Number of comments at the top level. Not returned for replies. total number? Total number of comments. Not retuned for replies. user_follow boolean is the current user watching the comment thread? user_votes number[] IDs of the comments in the bundle the current user has upvoted users UserCompact[] array of users related to the comments
CommentSort
Type Sort Fields new created_at (descending), id (descending) old created_at (ascending), id (ascending) top votes_count (descending), created_at (descending), id (descending)
Building cursor for comments listing
The returned response will be for comments after the specified sort fields.
For example, use last loaded comment for the fields value to load more comments. Also make sure to use same sort and parent_id values.
CommentableMeta
Metadata of the object that a comment is attached to.
Field Type Description id number the ID of the object title string display title type string the type of the object url string url of the object
CurrentUserAttributes
An object listing various related permissions and states for the current user, related to the object it is attached to.
BeatmapsetDiscussionPermissions
TODO: needs a better name.
Name Description can_destroy Can delete the discussion. can_reopen Can reopen the discussion. can_moderate_kudosu Can allow or deny kudosu. can_resolve Can resolve the discussion. vote_score Current vote given to the discussion.
ChatChannelUserAttributes
Name Type Description can_message boolean Can send messages to this channel. can_message_error string? Reason messages cannot be sent to this channel last_read_id number message_id of last message read.
Cursor
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.
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
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-07-06
2022-06-08
2021-10-28
2021-09-01
2021-08-11
2021-06-14
2021-06-09
2021-04-20
2021-02-25
2020-09-08
2020-08-28
2020-05-01
2020-02-18
2019-10-09
2019-07-18
Endpoint
Base URL
The base URL is: https://osu.ppy.sh/api/[version]/
API Versions
This is combined with the base endpoint to determine where requests should be sent.
Version Status v2 current (not yet public, consider unstable and expect breaking changes) v1 legacy api provided by the old site, will be deprecated soon
Authentication
Routes marked with the OAuth label require a valid OAuth2 token for access.
More information about applications you have registered and granted permissions to can be found here.
The API supports the following grant types:
Before you can use the osu!api, you will need to
Registering an OAuth application
Before you can get an OAuth token, you will need to register an OAuth application on your account settings page
To register an OAuth application you will need to provide the:
Name Description Application Name This is the name that will be visible to users of your application. The name of your application cannot be changed. Application Callback URL The URL in your application where users will be sent after authorization.
The Application Callback URL is required when for using Authorization Codes. This may be left blank if you are only using Client Credentials Grants.
Your new OAuth application will have a Client ID and Client Secret ; the Client Secret is like a password for your OAuth application, it should be kept private and do not share it with anyone else.
Authorization Code Grant
The flow to authorize users for your application is:
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:
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:
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.
Make sure to replace <> 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:
Name Description chat.write Allows sending chat messages on a user’s behalf. delegate Allows acting as the owner of a client; only available for Client Credentials Grant. forum.write Allows creating and editing forum posts on a user’s behalf. friends.read Allows reading of the user’s friend list. identify Allows reading of the public profile of the user ( /me ). public Allows reading of publicly available data on behalf of the user.
identify is the default scope for the Authorization Code Grant and always implicitly provided. The Client Credentials Grant does not currently have any default scopes.
Routes marked with lazer are intended for use by the osu!lazer client and not currently available for use with Authorization Code or Client Credentials grants.
Using the chat.write scope requires either
Managing OAuth applications
Your account settings page will show your registered OAuth applications, and all the OAuth applications you have granted permissions to.
Reset Client Secret
You can generate a new Client Secret by choosing to «Reset client secret», however, this will disable all access tokens issued for the application.
Beatmaps
Lookup Beatmap
Response format
Get a User Beatmap score
Return a User’s score on a Beatmap
Response Format
The position returned depends on the requested mode and mods.
Get a User Beatmap scores
Return a User’s scores on a Beatmap
Response Format
Get Beatmap scores
Returns the top scores for a beatmap
Response Format
Get Beatmap scores (temp)
Returns the top scores for a beatmap from newer client.
This is a temporary endpoint.
Response Format
Get Beatmaps
Returns list of beatmaps.
Response format
Field Type Description beatmaps BeatmapCompact[] Includes: beatmapset (with ratings), failtimes, max_combo.
Get Beatmap
Gets beatmap data for the specified beatmap ID.
Response format
Returns Beatmap object. Following attributes are included in the response object when applicable,
Attribute Notes beatmapset Includes ratings property. failtimes max_combo
Get Beatmap Attributes
Returns difficulty attributes of beatmap with specific mode and mods combination.
Response format
Beatmapset Discussions
Get Beatmapset Discussion Posts
Returns the posts of beatmapset discussions.
Response Format
Get Beatmapset Discussion Votes
Returns the votes given to beatmapset discussions.
Response Format
Get Beatmapset Discussions
Returns a list of beatmapset discussions.
Response Format
Changelog
Get Changelog Build
Returns details of the specified build.
Response Format
Get Changelog Listing
Returns a listing of update streams, builds, and changelog entries.
Response Format
Lookup Changelog Build
Returns details of the specified build.
Response Format
Create New PM
This endpoint allows you to create a new PM channel.
Response Format
Field Type new_channel_id channel_id of newly created ChatChannel presence array of ChatChannel message the sent ChatMessage
This endpoint will only allow the creation of PMs initially, group chat support will come later.
Get Updates
This endpoint returns new messages since the given message_id along with updated channel ‘presence’ data.
Response Format
Get Channel Messages
This endpoint returns the chat messages for a specific channel.
Response Format
Returns an array of ChatMessage
Send Message to Channel
This endpoint returns the chat messages for a specific channel.
Response Format
Join Channel
This endpoint allows you to join a public or multiplayer channel.
Response Format
Returns the joined ChatChannel.
Leave Channel
This endpoint allows you to leave a public channel.
Response Format
Mark Channel as Read
Response Format
Get Channel List
This endpoint returns a list of all joinable public channels.
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.
Response Format
Returns ChatChannel with recent_messages attribute. Note that in the case of PM s, 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.
Response Format
Field Type Description channel ChatChannel users UserCompact Users are only visible for PM channels.
Comments
Get Comments
Returns a list comments and their replies up to 2 levels deep.
Response Format
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.
Response Format
Get a Comment
Gets a comment and its replies up to 2 levels deep.
Response Format
Edit Comment
Edit an existing comment.
Response Format
Delete Comment
Deletes the specified comment.
Response Format
Add Comment vote
Upvotes a comment.
Response Format
Remove Comment vote
Un-upvotes a comment.
Response Format
Forum
Reply Topic
Create a post replying to the specified topic.
Response Format
ForumPost with body included.
Create Topic
Create a new topic.
Response Format
Get Topic and Posts
Get topic and its posts.
Response Format
Edit Topic
Edit topic. Only title can be edited through this endpoint.
Response Format
Edit Post
Edit specified forum post.
Response Format
ForumPost with body included.
Search
Searches users and wiki pages.
Response Format
SearchResult
Multiplayer
Get User High Score
Returns detail of highest score of specified user and the surrounding scores.
Response Format
Get Scores
Returns a list of scores for specified playlist item.
Response Format
Get a Score
Returns detail of specified score and the surrounding scores.
Response Format
Get News Listing
Returns a list of news posts and related metadata.
Response Format
Get News Post
Returns details of the specified news post.
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.
Response Format
Returns an object containing Notification and other related attributes.
Field Type has_more boolean whether or not there are more notifications notifications array of Notification unread_count total unread notifications notification_endpoint url to connect to websocket server
Mark Notifications as Read
This endpoint allows you to mark notifications read.
Response Format
OAuth Tokens
Revoke current token
Revokes currently authenticated token.
Ranking
Get Ranking
Gets the current ranking for the specified type and game mode.
Response Format
Get Spotlights
Gets the list of spotlights.
Response Format
Undocumented
/beatmaps//solo/scores
/beatmaps//solo/scores//beatmapsets/events
/beatmapsets//favourites
/chat/presence
/matches
/matches//rooms//rooms//users//rooms//users//rooms//leaderboard
/rooms//playlist//scores
/rooms//playlist//scores//reports
/rooms
/rooms//seasonal-backgrounds
/scores///download
/scores///beatmapsets/search//beatmapsets/lookup
/beatmapsets//friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
Similar to Get User but with authenticated user (token owner) as user id.
Response format
Additionally, statistics_rulesets is included, containing statistics for all rulesets.
Get User Kudosu
Returns kudosu history.
Response format
Get User Scores
This endpoint returns the scores of specified user.
Response format
Array of Score. Following attributes are included in the response object when applicable.
Get User Beatmaps
Returns the beatmaps of specified user.
Type Notes favourite graveyard loved most_played pending Previously unranked ranked Previously ranked_and_approved
Response format
Array of BeatmapPlaycount when type is most_played ; array of Beatmapset, otherwise.
Get User Recent Activity
Returns recent activity.
Response format
Get User
This endpoint returns the detail of specified user.
Response format
Returns User object. The following optional attributes on UserCompact are included:
Get Users
Returns list of users.
Response format
Field Type Description users UserCompact[] Includes: country, cover, groups, statistics_rulesets.
Get Wiki Page
The wiki article or image data.
Response Format
Notification Websocket
Connection
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:
Field Type Description event string See below
logout event
Server will disconnect session after sending this event so don’t try to reconnect.
Field Type Description event string logout
new event
New notification. See Notification object for notification types.
Field Type Description event string new data Notification
read event
Notification has been read.
Field Type Description event string read ids number[] id of Notifications which are read
Object Structures
Beatmap
Represent a beatmap. This extends BeatmapCompact with additional attributes.
Field Type Description accuracy float ar float beatmapset_id integer bpm float? convert boolean count_circles integer count_sliders integer count_spinners integer cs float deleted_at Timestamp? drain float hit_length integer is_scoreable boolean last_updated Timestamp mode_int integer passcount integer playcount integer ranked integer See Rank status for list of possible values. url string
BeatmapCompact
Represent a beatmap.
Field Type Description beatmapset_id integer difficulty_rating float id integer mode GameMode status string See Rank status for list of possible values. total_length integer user_id integer version string
Field Type Description beatmapset Beatmapset|BeatmapsetCompact|null Beatmapset for Beatmap object, BeatmapsetCompact for BeatmapCompact object. null if the beatmap doesn’t have associated beatmapset (e.g. deleted). checksum string? failtimes Failtimes max_combo integer
Failtimes
All fields are optional but there’s always at least one field returned.
Field Type Description exit integer[]? Array of length 100. fail integer[]? Array of length 100.
BeatmapDifficultyAttributes
Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.
Field Type max_combo integer star_rating float
Field Type aim_difficulty float approach_rate float flashlight_difficulty float overall_difficulty float slider_factor float speed_difficulty float
taiko
Field Type stamina_difficulty float rhythm_difficulty float colour_difficulty float approach_rate float great_hit_window float
fruits
mania
Field Type great_hit_window float score_multiplier float
BeatmapPlaycount
Represent the playcount of a beatmap.
Field Type Description beatmap_id number beatmap BeatmapCompact? beatmapset BeatmapsetCompact? count number
BeatmapScores
Field Type Description scores Score[] The list of top scores for the beatmap in descending order. userScore BeatmapUserScore? The score of the current user. This is not returned if the current user does not have a score. Note: will be moved to user_score in the future
BeatmapUserScore
Field Type Description position number The position of the score within the requested beatmap ranking. score Score The details of the score.
Beatmapset
Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.
Field Type Description availability.download_disabled boolean availability.more_information string? bpm float can_be_hyped boolean creator string Username of the mapper at the time of beatmapset creation. discussion_locked boolean hype.current integer hype.required integer is_scoreable boolean last_updated Timestamp legacy_thread_url string? nominations.current integer nominations.required integer ranked integer See Rank status for list of possible values. ranked_date Timestamp? source string storyboard boolean submitted_date Timestamp? tags string
The following attributes are always included as well:
Field has_favourited
BeatmapsetCompact
Represents a beatmapset.
Field Type Description artist string artist_unicode string covers Covers creator string favourite_count number id number nsfw boolean play_count number preview_url string source string status string title string title_unicode string user_id number video boolean
Those fields are optional.
Field Type Description beatmaps Beatmap[] converts current_user_attributes description discussions events genre has_favourited boolean language nominations ratings recent_favourites related_users user
Covers
Field Type cover string cover@2x string card string card@2x string list string list@2x string slimcover string slimcover@2x string
Rank status
The possible values are denoted either as integer or string.
Integer String -2 graveyard -1 wip 0 pending 1 ranked 2 approved 3 qualified 4 loved
BeatmapsetDiscussion
Represents a Beatmapset modding discussion.
Field Type Description beatmap BeatmapCompact? beatmap_id number? beatmapset BeatmapsetCompact? beatmapset_id number can_be_resolved boolean can_grant_kudosu boolean created_at Timestamp current_user_attributes CurrentUserAttributes deleted_at Timestamp? deleted_by_id number? id number kudosu_denied boolean last_post_at Timestamp message_type MessageType parent_id number? posts BeatmapsetDiscussionPost[]? resolved boolean starting_post BeatmapsetDiscussionPost? timestamp number? updated_at Timestamp user_id number
MessageType
Name Description hype mapper_note praise problem review suggestion
BeatmapsetDiscussionPost
Field Type Description beatmapset_discussion_id number created_at Timestamp deleted_at Timestamp? deleted_by_id number? id number last_editor_id number? message string system boolean updated_at Timestamp user_id number
BeatmapsetDiscussionVote
Field Type Description beatmapset_discussion_id number created_at Timestamp id number score number updated_at Timestamp user_id number
Build
Field Type created_at Timestamp display_version string id number update_stream UpdateStream? users number version string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes changelog_entries ChangelogEntry[] If the build has no changelog entries, a placeholder is generated. versions Versions
Versions
ChangelogEntry
Field Type category string created_at Timestamp? github_pull_request_id number? github_url string? id number? major boolean repository string? title string? type string url string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes github_user GithubUser If the changelog entry has no GitHub user, a placeholder is generated. message string? Entry message in Markdown format. Embedded HTML is allowed. message_html string? Entry message in HTML format.
ChatChannel
Represents an individual chat «channel» in the game.
Channel Types
Type Permission Check for Joining/Messaging PUBLIC PRIVATE is player in the allowed groups? (channel.allowed_groups) MULTIPLAYER is player currently in the mp game? SPECTATOR TEMPORARY deprecated PM see below (user_channels) GROUP is player in channel? (user_channels)
For PMs, two factors are taken into account:
ChatMessage
Represents an individual Message within a ChatChannel.
Field Type Description message_id number unique identifier for message sender_id number user_id of the sender channel_id number channel_id of where the message was sent timestamp string when the message was sent, ISO-8601 content string message content is_action boolean was this an action? i.e. /me dances sender UserCompact embedded UserCompact object to save additional api lookups
Comment
Represents an single comment.
Field Type Description commentable_id number ID of the object the comment is attached to commentable_type string type of object the comment is attached to created_at string ISO 8601 date deleted_at string? ISO 8601 date if the comment was deleted; null, otherwise edited_at string? ISO 8601 date if the comment was edited; null, otherwise edited_by_id number? user id of the user that edited the post; null, otherwise id number the ID of the comment legacy_name string? username displayed on legacy comments message string? markdown of the comment’s content message_html string? html version of the comment’s content parent_id number? ID of the comment’s parent pinned boolean Pin status of the comment replies_count number number of replies to the comment updated_at string ISO 8601 date user_id number user ID of the poster votes_count number number of votes
CommentBundle
Comments and related data.
Field Type Description commentable_meta CommentableMeta[] ID of the object the comment is attached to comments Comment[] Array of comments ordered according to sort ; cursor Cursor has_more boolean If there are more comments or replies available has_more_id number? included_comments Comment[] Related comments; e.g. parent comments and nested replies pinned_comments Comment[]? Pinned comments sort string one of the CommentSort types top_level_count number? Number of comments at the top level. Not returned for replies. total number? Total number of comments. Not retuned for replies. user_follow boolean is the current user watching the comment thread? user_votes number[] IDs of the comments in the bundle the current user has upvoted users UserCompact[] array of users related to the comments
CommentSort
Type Sort Fields new created_at (descending), id (descending) old created_at (ascending), id (ascending) top votes_count (descending), created_at (descending), id (descending)
Building cursor for comments listing
The returned response will be for comments after the specified sort fields.
For example, use last loaded comment for the fields value to load more comments. Also make sure to use same sort and parent_id values.
CommentableMeta
Metadata of the object that a comment is attached to.
Field Type Description id number the ID of the object title string display title type string the type of the object url string url of the object
CurrentUserAttributes
An object listing various related permissions and states for the current user, related to the object it is attached to.
BeatmapsetDiscussionPermissions
TODO: needs a better name.
Name Description can_destroy Can delete the discussion. can_reopen Can reopen the discussion. can_moderate_kudosu Can allow or deny kudosu. can_resolve Can resolve the discussion. vote_score Current vote given to the discussion.
ChatChannelUserAttributes
Name Type Description can_message boolean Can send messages to this channel. can_message_error string? Reason messages cannot be sent to this channel last_read_id number message_id of last message read.
Cursor
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.
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
osu!api open beta
Нет аккаунта?
osu!api open beta
I’ve had an API available for a while but until now it has been on a private on-request basis. In order to try and make developing third party services which expand and support osu!, I have added an API key setup and started to document the API.
Documentation will be expanded as I find time to do so! If anyone currently using the API is able to help expand the documentation then please do.
comentarinformal wrote:
Before I spam it with requests that might not exist, is there anything to get user’s information?
(Also, is there anything to login users from this page in other places?)
There is /api/get_user
Gonna write an entry with the information I have about it.
Is there a fair use limit? (e.g. no more than XX requests per day)
For get_user, I suppose there is a mode parameter for getting user information for Taiko, CtB and osu!mania? Or do I have to file an issue in GitHub? Nevermind, I found it, the parameter to add is called «m» I have edited the GitHub wiki.
Oh well. I have some questions:
Are only the beatmap and user endpoints available?
The parameter «since» in /get_beatmap how I need to pass the time on it? UTC or unix timestamp?
Do I need to pass the key on the wiki’s API too?
Edit: What the countX values mean? Number of beatmaps?
comentarinformal wrote:
Before I spam it with requests that might not exist, is there anything to get user’s information?
(Also, is there anything to login users from this page in other places?)
I guess I’ll update my userbar too when I find some time.
Damnae wrote:
I guess I’ll update my userbar too when I find some time.
I registered it for osu!userbar, but I also use it for my «Big ugly white signature», they are not on the same webserver, but it works fine
I belive only you and peppy can see the name you used, too.
(Yes I took my lazyness off, it was not that long to update ^^)
@Repflez: I tried using your API-powered signature and I get something weird.
Since I only aim for SS, I have 100% Accuracy all the time, and the Accuracy display is weird.
(I now know that despite having all-SS records, the note hit count for getting 50s and 100s are still counted all the time )
Winshley wrote:
@Repflez: I tried using your API-powered signature and I get something weird.
Since I only aim for SS, I have 100% Accuracy all the time, and the Accuracy display is weird.
(I now know that despite having all-SS records, the note hit count for getting 50s and 100s are still counted all the time )
So that’s what the CountX values mean. Thanks for that. I already went and changed the accuracy to show a centered «100% Accuracy» if it’s 100. Forget that. I ditched the bar on it and used the extra space for showing the PP.
(I love how the 300 count ended overlaping the border)
Repflez wrote:
So that’s what the CountX values mean. Thanks for that.
Yeah. At first I thought that there was something wrong with the API showing 50s and 100s despite having 100% Accuracy, until I actually calculated all 300s + 100s + 50s = «Total Hits» on our profile.
About the 300 overlap though, it does need some fix:
When you reached 10 millions of 300 hits, the last number is cut off. Cookiezi has 17 millions of 300 hits.
I’m not sure how the level bar breaking happens though. I was thinking that it probably because I don’t have any ranked score on osu!mania?
[Archived] getting osu! api token
Нет аккаунта?
[Archived] getting osu! api token
here is the website I am currently using this for https://osu-api-crap.minecreeper0913.repl.co
well since the project I am using is all python and not javascript I am using a new tab browser to just test it and so far the code I am using is
url = («https://osu.ppy.sh/oauth/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=%s» % (code))
the &code=%s is basically just grabbing the code that has been given back by oauth and using that as the url, when I am testing it though I am actually using my code
Never share your client secret, it’s secret for a reason. I would recommend resetting it ASAP.
Are you just typing that URL into your browser or are you actually sending it as a post request with whatever python code you have? Typing the URL into your browser won’t work.
The token endpoint takes the parameters in the body of the request, not as query parameters. You are also missing some parameters, like redirect_uri and grant_type.
If you are using python’s requests library, you can do something like this:
Might have some syntax errors because I wrote that from memory and didn’t check anything in an IDE or by running it.
You can try without specifying the content type in your headers, it might work without it. Very simply, the content type header describes what type of content or data is being sent. As far as I recall, the server is expecting that content type but I could be wrong.
now starting to realize that I might have done this a bit wrong, this is the first time I have used an API for something so everything I am doing is new to me.
So the first thing that is happening is that you press the login to link your osu API to the website, then it grabs your code and redirects you to the home website with the code in the url for example http://www.website.com/code=j9838r9y82g9438gh8243hg384hg, and it is supposed to use that, but when in testing it just returns favicon.ico, and I don’t know what that is or means so I might have to change my get request, another issue is but how would I make it get that auth code?
I don’t know anything about the project you are working on, so unfortunately I don’t think I can really answer any of the questions you’re asking.
I don’t know what you mean by a favicon being returned and I also don’t know what you are using the handle the backend of your site, so I can’t specifically tell you how to grab the code. Whatever you are using should have some way of getting query parameters from the URL.
Oauth2 is a very standardized and should be nearly the same everywhere that uses it. osu! is no exception. I would highly recommend looking up and reading about the authorization code flow that you are trying to use here. There should be a ton of resources and maybe a few code examples as well.
There might not be any videos specific to osu!’s API, but there are definitely Oauth2 tutorial videos and examples out there in probably every programming language, which is what you are dealing with right now.
For example, here is a video I found after a quick Google search that is using Python. I can’t fully comment on its quality since I just skimmed through it, but the general flow that the creator of the video goes over seems like it will at least cover how OAuth2 works in general, even if it’s not in the context of osu!’s API.
And even if you don’t really like reading, there are still some pretty good resources you can use that might help in addition to watching a video. Like this and this for example. Again, I’ve only skimmed through these, but they also seem to be pretty good.
here is the code I use:
NOTE I did not actually use SECRET as the secret I have it as SECRET because its secret
/beatmapsets/search//beatmapsets/lookup
/beatmapsets//friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
/friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
Similar to Get User but with authenticated user (token owner) as user id.
Response format
Additionally, statistics_rulesets is included, containing statistics for all rulesets.
Get User Kudosu
Returns kudosu history.
Response format
Get User Scores
This endpoint returns the scores of specified user.
Response format
Array of Score. Following attributes are included in the response object when applicable.
Get User Beatmaps
Returns the beatmaps of specified user.
| Type | Notes |
|---|---|
| favourite | |
| graveyard | |
| loved | |
| most_played | |
| pending | Previously unranked |
| ranked | Previously ranked_and_approved |
Response format
Array of BeatmapPlaycount when type is most_played ; array of Beatmapset, otherwise.
Get User Recent Activity
Returns recent activity.
Response format
Get User
This endpoint returns the detail of specified user.
Response format
Returns User object. The following optional attributes on UserCompact are included:
Get Users
Returns list of users.
Response format
| Field | Type | Description |
|---|---|---|
| users | UserCompact[] | Includes: country, cover, groups, statistics_rulesets. |
Get Wiki Page
The wiki article or image data.
Response Format
Notification Websocket
Connection
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:
| Field | Type | Description |
|---|---|---|
| event | string | See below |
logout event
Server will disconnect session after sending this event so don’t try to reconnect.
| Field | Type | Description |
|---|---|---|
| event | string | logout |
new event
New notification. See Notification object for notification types.
| Field | Type | Description |
|---|---|---|
| event | string | new |
| data | Notification |
read event
Notification has been read.
| Field | Type | Description |
|---|---|---|
| event | string | read |
| ids | number[] | id of Notifications which are read |
Object Structures
Beatmap
Represent a beatmap. This extends BeatmapCompact with additional attributes.
| Field | Type | Description |
|---|---|---|
| accuracy | float | |
| ar | float | |
| beatmapset_id | integer | |
| bpm | float? | |
| convert | boolean | |
| count_circles | integer | |
| count_sliders | integer | |
| count_spinners | integer | |
| cs | float | |
| deleted_at | Timestamp? | |
| drain | float | |
| hit_length | integer | |
| is_scoreable | boolean | |
| last_updated | Timestamp | |
| mode_int | integer | |
| passcount | integer | |
| playcount | integer | |
| ranked | integer | See Rank status for list of possible values. |
| url | string |
BeatmapCompact
Represent a beatmap.
| Field | Type | Description |
|---|---|---|
| beatmapset_id | integer | |
| difficulty_rating | float | |
| id | integer | |
| mode | GameMode | |
| status | string | See Rank status for list of possible values. |
| total_length | integer | |
| user_id | integer | |
| version | string |
| Field | Type | Description |
|---|---|---|
| beatmapset | Beatmapset|BeatmapsetCompact|null | Beatmapset for Beatmap object, BeatmapsetCompact for BeatmapCompact object. null if the beatmap doesn’t have associated beatmapset (e.g. deleted). |
| checksum | string? | |
| failtimes | Failtimes | |
| max_combo | integer |
Failtimes
All fields are optional but there’s always at least one field returned.
| Field | Type | Description |
|---|---|---|
| exit | integer[]? | Array of length 100. |
| fail | integer[]? | Array of length 100. |
BeatmapDifficultyAttributes
Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.
| Field | Type |
|---|---|
| max_combo | integer |
| star_rating | float |
| Field | Type |
|---|---|
| aim_difficulty | float |
| approach_rate | float |
| flashlight_difficulty | float |
| overall_difficulty | float |
| slider_factor | float |
| speed_difficulty | float |
taiko
| Field | Type |
|---|---|
| stamina_difficulty | float |
| rhythm_difficulty | float |
| colour_difficulty | float |
| approach_rate | float |
| great_hit_window | float |
fruits
mania
| Field | Type |
|---|---|
| great_hit_window | float |
| score_multiplier | float |
BeatmapPlaycount
Represent the playcount of a beatmap.
| Field | Type | Description |
|---|---|---|
| beatmap_id | number | |
| beatmap | BeatmapCompact? | |
| beatmapset | BeatmapsetCompact? | |
| count | number |
BeatmapScores
| Field | Type | Description |
|---|---|---|
| scores | Score[] | The list of top scores for the beatmap in descending order. |
| userScore | BeatmapUserScore? | The score of the current user. This is not returned if the current user does not have a score. Note: will be moved to user_score in the future |
BeatmapUserScore
| Field | Type | Description |
|---|---|---|
| position | number | The position of the score within the requested beatmap ranking. |
| score | Score | The details of the score. |
Beatmapset
Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.
| Field | Type | Description |
|---|---|---|
| availability.download_disabled | boolean | |
| availability.more_information | string? | |
| bpm | float | |
| can_be_hyped | boolean | |
| creator | string | Username of the mapper at the time of beatmapset creation. |
| discussion_locked | boolean | |
| hype.current | integer | |
| hype.required | integer | |
| is_scoreable | boolean | |
| last_updated | Timestamp | |
| legacy_thread_url | string? | |
| nominations.current | integer | |
| nominations.required | integer | |
| ranked | integer | See Rank status for list of possible values. |
| ranked_date | Timestamp? | |
| source | string | |
| storyboard | boolean | |
| submitted_date | Timestamp? | |
| tags | string |
The following attributes are always included as well:
| Field |
|---|
| has_favourited |
BeatmapsetCompact
Represents a beatmapset.
| Field | Type | Description |
|---|---|---|
| artist | string | |
| artist_unicode | string | |
| covers | Covers | |
| creator | string | |
| favourite_count | number | |
| id | number | |
| nsfw | boolean | |
| play_count | number | |
| preview_url | string | |
| source | string | |
| status | string | |
| title | string | |
| title_unicode | string | |
| user_id | number | |
| video | boolean |
Those fields are optional.
| Field | Type | Description |
|---|---|---|
| beatmaps | Beatmap[] | |
| converts | ||
| current_user_attributes | ||
| description | ||
| discussions | ||
| events | ||
| genre | ||
| has_favourited | boolean | |
| language | ||
| nominations | ||
| ratings | ||
| recent_favourites | ||
| related_users | ||
| user |
Covers
| Field | Type |
|---|---|
| cover | string |
| cover@2x | string |
| card | string |
| card@2x | string |
| list | string |
| list@2x | string |
| slimcover | string |
| slimcover@2x | string |
Rank status
The possible values are denoted either as integer or string.
| Integer | String |
|---|---|
| -2 | graveyard |
| -1 | wip |
| 0 | pending |
| 1 | ranked |
| 2 | approved |
| 3 | qualified |
| 4 | loved |
BeatmapsetDiscussion
Represents a Beatmapset modding discussion.
| Field | Type | Description |
|---|---|---|
| beatmap | BeatmapCompact? | |
| beatmap_id | number? | |
| beatmapset | BeatmapsetCompact? | |
| beatmapset_id | number | |
| can_be_resolved | boolean | |
| can_grant_kudosu | boolean | |
| created_at | Timestamp | |
| current_user_attributes | CurrentUserAttributes | |
| deleted_at | Timestamp? | |
| deleted_by_id | number? | |
| id | number | |
| kudosu_denied | boolean | |
| last_post_at | Timestamp | |
| message_type | MessageType | |
| parent_id | number? | |
| posts | BeatmapsetDiscussionPost[]? | |
| resolved | boolean | |
| starting_post | BeatmapsetDiscussionPost? | |
| timestamp | number? | |
| updated_at | Timestamp | |
| user_id | number |
MessageType
| Name | Description |
|---|---|
| hype | |
| mapper_note | |
| praise | |
| problem | |
| review | |
| suggestion |
BeatmapsetDiscussionPost
| Field | Type | Description |
|---|---|---|
| beatmapset_discussion_id | number | |
| created_at | Timestamp | |
| deleted_at | Timestamp? | |
| deleted_by_id | number? | |
| id | number | |
| last_editor_id | number? | |
| message | string | |
| system | boolean | |
| updated_at | Timestamp | |
| user_id | number |
BeatmapsetDiscussionVote
| Field | Type | Description |
|---|---|---|
| beatmapset_discussion_id | number | |
| created_at | Timestamp | |
| id | number | |
| score | number | |
| updated_at | Timestamp | |
| user_id | number |
Build
| Field | Type |
|---|---|
| created_at | Timestamp |
| display_version | string |
| id | number |
| update_stream | UpdateStream? |
| users | number |
| version | string? |
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
| Field | Type | Notes |
|---|---|---|
| changelog_entries | ChangelogEntry[] | If the build has no changelog entries, a placeholder is generated. |
| versions | Versions |
Versions
ChangelogEntry
| Field | Type |
|---|---|
| category | string |
| created_at | Timestamp? |
| github_pull_request_id | number? |
| github_url | string? |
| id | number? |
| major | boolean |
| repository | string? |
| title | string? |
| type | string |
| url | string? |
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
| Field | Type | Notes |
|---|---|---|
| github_user | GithubUser | If the changelog entry has no GitHub user, a placeholder is generated. |
| message | string? | Entry message in Markdown format. Embedded HTML is allowed. |
| message_html | string? | Entry message in HTML format. |
ChatChannel
Represents an individual chat «channel» in the game.
Channel Types
| Type | Permission Check for Joining/Messaging |
|---|---|
| PUBLIC | |
| PRIVATE | is player in the allowed groups? (channel.allowed_groups) |
| MULTIPLAYER | is player currently in the mp game? |
| SPECTATOR | |
| TEMPORARY | deprecated |
| PM | see below (user_channels) |
| GROUP | is player in channel? (user_channels) |
For PMs, two factors are taken into account:
ChatMessage
Represents an individual Message within a ChatChannel.
| Field | Type | Description |
|---|---|---|
| message_id | number | unique identifier for message |
| sender_id | number | user_id of the sender |
| channel_id | number | channel_id of where the message was sent |
| timestamp | string | when the message was sent, ISO-8601 |
| content | string | message content |
| is_action | boolean | was this an action? i.e. /me dances |
| sender | UserCompact | embedded UserCompact object to save additional api lookups |
Comment
Represents an single comment.
| Field | Type | Description |
|---|---|---|
| commentable_id | number | ID of the object the comment is attached to |
| commentable_type | string | type of object the comment is attached to |
| created_at | string | ISO 8601 date |
| deleted_at | string? | ISO 8601 date if the comment was deleted; null, otherwise |
| edited_at | string? | ISO 8601 date if the comment was edited; null, otherwise |
| edited_by_id | number? | user id of the user that edited the post; null, otherwise |
| id | number | the ID of the comment |
| legacy_name | string? | username displayed on legacy comments |
| message | string? | markdown of the comment’s content |
| message_html | string? | html version of the comment’s content |
| parent_id | number? | ID of the comment’s parent |
| pinned | boolean | Pin status of the comment |
| replies_count | number | number of replies to the comment |
| updated_at | string | ISO 8601 date |
| user_id | number | user ID of the poster |
| votes_count | number | number of votes |
CommentBundle
Comments and related data.
| Field | Type | Description |
|---|---|---|
| commentable_meta | CommentableMeta[] | ID of the object the comment is attached to |
| comments | Comment[] | Array of comments ordered according to sort ; |
| cursor | Cursor | |
| has_more | boolean | If there are more comments or replies available |
| has_more_id | number? | |
| included_comments | Comment[] | Related comments; e.g. parent comments and nested replies |
| pinned_comments | Comment[]? | Pinned comments |
| sort | string | one of the CommentSort types |
| top_level_count | number? | Number of comments at the top level. Not returned for replies. |
| total | number? | Total number of comments. Not retuned for replies. |
| user_follow | boolean | is the current user watching the comment thread? |
| user_votes | number[] | IDs of the comments in the bundle the current user has upvoted |
| users | UserCompact[] | array of users related to the comments |
CommentSort
| Type | Sort Fields |
|---|---|
| new | created_at (descending), id (descending) |
| old | created_at (ascending), id (ascending) |
| top | votes_count (descending), created_at (descending), id (descending) |
Building cursor for comments listing
The returned response will be for comments after the specified sort fields.
For example, use last loaded comment for the fields value to load more comments. Also make sure to use same sort and parent_id values.
CommentableMeta
Metadata of the object that a comment is attached to.
| Field | Type | Description |
|---|---|---|
| id | number | the ID of the object |
| title | string | display title |
| type | string | the type of the object |
| url | string | url of the object |
CurrentUserAttributes
An object listing various related permissions and states for the current user, related to the object it is attached to.
BeatmapsetDiscussionPermissions
TODO: needs a better name.
| Name | Description |
|---|---|
| can_destroy | Can delete the discussion. |
| can_reopen | Can reopen the discussion. |
| can_moderate_kudosu | Can allow or deny kudosu. |
| can_resolve | Can resolve the discussion. |
| vote_score | Current vote given to the discussion. |
ChatChannelUserAttributes
| Name | Type | Description |
|---|---|---|
| can_message | boolean | Can send messages to this channel. |
| can_message_error | string? | Reason messages cannot be sent to this channel |
| last_read_id | number | message_id of last message read. |
Cursor
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.
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
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-07-06
2022-06-08
2021-10-28
2021-09-01
2021-08-11
2021-06-14
2021-06-09
2021-04-20
2021-02-25
2020-09-08
2020-08-28
2020-05-01
2020-02-18
2019-10-09
2019-07-18
Endpoint
Base URL
The base URL is: https://osu.ppy.sh/api/[version]/
API Versions
This is combined with the base endpoint to determine where requests should be sent.
| Version | Status |
|---|---|
| v2 | current (not yet public, consider unstable and expect breaking changes) |
| v1 | legacy api provided by the old site, will be deprecated soon |
Authentication
Routes marked with the OAuth label require a valid OAuth2 token for access.
More information about applications you have registered and granted permissions to can be found here.
The API supports the following grant types:
Before you can use the osu!api, you will need to
Registering an OAuth application
Before you can get an OAuth token, you will need to register an OAuth application on your account settings page
To register an OAuth application you will need to provide the:
| Name | Description |
|---|---|
| Application Name | This is the name that will be visible to users of your application. The name of your application cannot be changed. |
| Application Callback URL | The URL in your application where users will be sent after authorization. |
The Application Callback URL is required when for using Authorization Codes. This may be left blank if you are only using Client Credentials Grants.
Your new OAuth application will have a Client ID and Client Secret ; the Client Secret is like a password for your OAuth application, it should be kept private and do not share it with anyone else.
Authorization Code Grant
The flow to authorize users for your application is:
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:
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:
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.
Make sure to replace <
> 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:
| Name | Description |
|---|---|
| chat.write | Allows sending chat messages on a user’s behalf. |
| delegate | Allows acting as the owner of a client; only available for Client Credentials Grant. |
| forum.write | Allows creating and editing forum posts on a user’s behalf. |
| friends.read | Allows reading of the user’s friend list. |
| identify | Allows reading of the public profile of the user ( /me ). |
| public | Allows reading of publicly available data on behalf of the user. |
identify is the default scope for the Authorization Code Grant and always implicitly provided. The Client Credentials Grant does not currently have any default scopes.
Routes marked with lazer are intended for use by the osu!lazer client and not currently available for use with Authorization Code or Client Credentials grants.
Using the chat.write scope requires either
Managing OAuth applications
Your account settings page will show your registered OAuth applications, and all the OAuth applications you have granted permissions to.
Reset Client Secret
You can generate a new Client Secret by choosing to «Reset client secret», however, this will disable all access tokens issued for the application.
Beatmaps
Lookup Beatmap
Response format
Get a User Beatmap score
Return a User’s score on a Beatmap
Response Format
The position returned depends on the requested mode and mods.
Get a User Beatmap scores
Return a User’s scores on a Beatmap
Response Format
Get Beatmap scores
Returns the top scores for a beatmap
Response Format
Get Beatmap scores (temp)
Returns the top scores for a beatmap from newer client.
This is a temporary endpoint.
Response Format
Get Beatmaps
Returns list of beatmaps.
Response format
| Field | Type | Description |
|---|---|---|
| beatmaps | BeatmapCompact[] | Includes: beatmapset (with ratings), failtimes, max_combo. |
Get Beatmap
Gets beatmap data for the specified beatmap ID.
Response format
Returns Beatmap object. Following attributes are included in the response object when applicable,
| Attribute | Notes |
|---|---|
| beatmapset | Includes ratings property. |
| failtimes | |
| max_combo |
Get Beatmap Attributes
Returns difficulty attributes of beatmap with specific mode and mods combination.
Response format
Beatmapset Discussions
Get Beatmapset Discussion Posts
Returns the posts of beatmapset discussions.
Response Format
Get Beatmapset Discussion Votes
Returns the votes given to beatmapset discussions.
Response Format
Get Beatmapset Discussions
Returns a list of beatmapset discussions.
Response Format
Changelog
Get Changelog Build
Returns details of the specified build.
Response Format
Get Changelog Listing
Returns a listing of update streams, builds, and changelog entries.
Response Format
Lookup Changelog Build
Returns details of the specified build.
Response Format
Create New PM
This endpoint allows you to create a new PM channel.
Response Format
| Field | Type |
|---|---|
| new_channel_id | channel_id of newly created ChatChannel |
| presence | array of ChatChannel |
| message | the sent ChatMessage |
This endpoint will only allow the creation of PMs initially, group chat support will come later.
Get Updates
This endpoint returns new messages since the given message_id along with updated channel ‘presence’ data.
Response Format
Get Channel Messages
This endpoint returns the chat messages for a specific channel.
Response Format
Returns an array of ChatMessage
Send Message to Channel
This endpoint returns the chat messages for a specific channel.
Response Format
Join Channel
This endpoint allows you to join a public or multiplayer channel.
Response Format
Returns the joined ChatChannel.
Leave Channel
This endpoint allows you to leave a public channel.
Response Format
Mark Channel as Read
Response Format
Get Channel List
This endpoint returns a list of all joinable public channels.
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.
Response Format
Returns ChatChannel with recent_messages attribute. Note that in the case of PM s, 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.
Response Format
| Field | Type | Description |
|---|---|---|
| channel | ChatChannel | |
| users | UserCompact | Users are only visible for PM channels. |
Comments
Get Comments
Returns a list comments and their replies up to 2 levels deep.
Response Format
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.
Response Format
Get a Comment
Gets a comment and its replies up to 2 levels deep.
Response Format
Edit Comment
Edit an existing comment.
Response Format
Delete Comment
Deletes the specified comment.
Response Format
Add Comment vote
Upvotes a comment.
Response Format
Remove Comment vote
Un-upvotes a comment.
Response Format
Forum
Reply Topic
Create a post replying to the specified topic.
Response Format
ForumPost with body included.
Create Topic
Create a new topic.
Response Format
Get Topic and Posts
Get topic and its posts.
Response Format
Edit Topic
Edit topic. Only title can be edited through this endpoint.
Response Format
Edit Post
Edit specified forum post.
Response Format
ForumPost with body included.
Search
Searches users and wiki pages.
Response Format
SearchResult
Multiplayer
Get User High Score
Returns detail of highest score of specified user and the surrounding scores.
Response Format
Get Scores
Returns a list of scores for specified playlist item.
Response Format
Get a Score
Returns detail of specified score and the surrounding scores.
Response Format
Get News Listing
Returns a list of news posts and related metadata.
Response Format
Get News Post
Returns details of the specified news post.
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.
Response Format
Returns an object containing Notification and other related attributes.
| Field | Type |
|---|---|
| has_more | boolean whether or not there are more notifications |
| notifications | array of Notification |
| unread_count | total unread notifications |
| notification_endpoint | url to connect to websocket server |
Mark Notifications as Read
This endpoint allows you to mark notifications read.
Response Format
OAuth Tokens
Revoke current token
Revokes currently authenticated token.
Ranking
Get Ranking
Gets the current ranking for the specified type and game mode.
Response Format
Get Spotlights
Gets the list of spotlights.
Response Format
Undocumented
/beatmaps//solo/scores
/beatmaps//solo/scores//beatmapsets/events
/beatmapsets//favourites
/chat/presence
/matches
/matches//rooms//rooms//users//rooms//users//rooms//leaderboard
/rooms//playlist//scores
/rooms//playlist//scores//reports
/rooms
/rooms//seasonal-backgrounds
/scores///download
/scores///beatmapsets/search//beatmapsets/lookup
/beatmapsets//friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
Similar to Get User but with authenticated user (token owner) as user id.
Response format
Additionally, statistics_rulesets is included, containing statistics for all rulesets.
Get User Kudosu
Returns kudosu history.
Response format
Get User Scores
This endpoint returns the scores of specified user.
Response format
Array of Score. Following attributes are included in the response object when applicable.
Get User Beatmaps
Returns the beatmaps of specified user.
Type Notes favourite graveyard loved most_played pending Previously unranked ranked Previously ranked_and_approved
Response format
Array of BeatmapPlaycount when type is most_played ; array of Beatmapset, otherwise.
Get User Recent Activity
Returns recent activity.
Response format
Get User
This endpoint returns the detail of specified user.
Response format
Returns User object. The following optional attributes on UserCompact are included:
Get Users
Returns list of users.
Response format
Field Type Description users UserCompact[] Includes: country, cover, groups, statistics_rulesets.
Get Wiki Page
The wiki article or image data.
Response Format
Notification Websocket
Connection
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:
Field Type Description event string See below
logout event
Server will disconnect session after sending this event so don’t try to reconnect.
Field Type Description event string logout
new event
New notification. See Notification object for notification types.
Field Type Description event string new data Notification
read event
Notification has been read.
Field Type Description event string read ids number[] id of Notifications which are read
Object Structures
Beatmap
Represent a beatmap. This extends BeatmapCompact with additional attributes.
Field Type Description accuracy float ar float beatmapset_id integer bpm float? convert boolean count_circles integer count_sliders integer count_spinners integer cs float deleted_at Timestamp? drain float hit_length integer is_scoreable boolean last_updated Timestamp mode_int integer passcount integer playcount integer ranked integer See Rank status for list of possible values. url string
BeatmapCompact
Represent a beatmap.
Field Type Description beatmapset_id integer difficulty_rating float id integer mode GameMode status string See Rank status for list of possible values. total_length integer user_id integer version string
Field Type Description beatmapset Beatmapset|BeatmapsetCompact|null Beatmapset for Beatmap object, BeatmapsetCompact for BeatmapCompact object. null if the beatmap doesn’t have associated beatmapset (e.g. deleted). checksum string? failtimes Failtimes max_combo integer
Failtimes
All fields are optional but there’s always at least one field returned.
Field Type Description exit integer[]? Array of length 100. fail integer[]? Array of length 100.
BeatmapDifficultyAttributes
Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.
Field Type max_combo integer star_rating float
Field Type aim_difficulty float approach_rate float flashlight_difficulty float overall_difficulty float slider_factor float speed_difficulty float
taiko
Field Type stamina_difficulty float rhythm_difficulty float colour_difficulty float approach_rate float great_hit_window float
fruits
mania
Field Type great_hit_window float score_multiplier float
BeatmapPlaycount
Represent the playcount of a beatmap.
Field Type Description beatmap_id number beatmap BeatmapCompact? beatmapset BeatmapsetCompact? count number
BeatmapScores
Field Type Description scores Score[] The list of top scores for the beatmap in descending order. userScore BeatmapUserScore? The score of the current user. This is not returned if the current user does not have a score. Note: will be moved to user_score in the future
BeatmapUserScore
Field Type Description position number The position of the score within the requested beatmap ranking. score Score The details of the score.
Beatmapset
Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.
Field Type Description availability.download_disabled boolean availability.more_information string? bpm float can_be_hyped boolean creator string Username of the mapper at the time of beatmapset creation. discussion_locked boolean hype.current integer hype.required integer is_scoreable boolean last_updated Timestamp legacy_thread_url string? nominations.current integer nominations.required integer ranked integer See Rank status for list of possible values. ranked_date Timestamp? source string storyboard boolean submitted_date Timestamp? tags string
The following attributes are always included as well:
Field has_favourited
BeatmapsetCompact
Represents a beatmapset.
Field Type Description artist string artist_unicode string covers Covers creator string favourite_count number id number nsfw boolean play_count number preview_url string source string status string title string title_unicode string user_id number video boolean
Those fields are optional.
Field Type Description beatmaps Beatmap[] converts current_user_attributes description discussions events genre has_favourited boolean language nominations ratings recent_favourites related_users user
Covers
Field Type cover string cover@2x string card string card@2x string list string list@2x string slimcover string slimcover@2x string
Rank status
The possible values are denoted either as integer or string.
Integer String -2 graveyard -1 wip 0 pending 1 ranked 2 approved 3 qualified 4 loved
BeatmapsetDiscussion
Represents a Beatmapset modding discussion.
Field Type Description beatmap BeatmapCompact? beatmap_id number? beatmapset BeatmapsetCompact? beatmapset_id number can_be_resolved boolean can_grant_kudosu boolean created_at Timestamp current_user_attributes CurrentUserAttributes deleted_at Timestamp? deleted_by_id number? id number kudosu_denied boolean last_post_at Timestamp message_type MessageType parent_id number? posts BeatmapsetDiscussionPost[]? resolved boolean starting_post BeatmapsetDiscussionPost? timestamp number? updated_at Timestamp user_id number
MessageType
Name Description hype mapper_note praise problem review suggestion
BeatmapsetDiscussionPost
Field Type Description beatmapset_discussion_id number created_at Timestamp deleted_at Timestamp? deleted_by_id number? id number last_editor_id number? message string system boolean updated_at Timestamp user_id number
BeatmapsetDiscussionVote
Field Type Description beatmapset_discussion_id number created_at Timestamp id number score number updated_at Timestamp user_id number
Build
Field Type created_at Timestamp display_version string id number update_stream UpdateStream? users number version string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes changelog_entries ChangelogEntry[] If the build has no changelog entries, a placeholder is generated. versions Versions
Versions
ChangelogEntry
Field Type category string created_at Timestamp? github_pull_request_id number? github_url string? id number? major boolean repository string? title string? type string url string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes github_user GithubUser If the changelog entry has no GitHub user, a placeholder is generated. message string? Entry message in Markdown format. Embedded HTML is allowed. message_html string? Entry message in HTML format.
ChatChannel
Represents an individual chat «channel» in the game.
Channel Types
Type Permission Check for Joining/Messaging PUBLIC PRIVATE is player in the allowed groups? (channel.allowed_groups) MULTIPLAYER is player currently in the mp game? SPECTATOR TEMPORARY deprecated PM see below (user_channels) GROUP is player in channel? (user_channels)
For PMs, two factors are taken into account:
ChatMessage
Represents an individual Message within a ChatChannel.
Field Type Description message_id number unique identifier for message sender_id number user_id of the sender channel_id number channel_id of where the message was sent timestamp string when the message was sent, ISO-8601 content string message content is_action boolean was this an action? i.e. /me dances sender UserCompact embedded UserCompact object to save additional api lookups
Comment
Represents an single comment.
Field Type Description commentable_id number ID of the object the comment is attached to commentable_type string type of object the comment is attached to created_at string ISO 8601 date deleted_at string? ISO 8601 date if the comment was deleted; null, otherwise edited_at string? ISO 8601 date if the comment was edited; null, otherwise edited_by_id number? user id of the user that edited the post; null, otherwise id number the ID of the comment legacy_name string? username displayed on legacy comments message string? markdown of the comment’s content message_html string? html version of the comment’s content parent_id number? ID of the comment’s parent pinned boolean Pin status of the comment replies_count number number of replies to the comment updated_at string ISO 8601 date user_id number user ID of the poster votes_count number number of votes
CommentBundle
Comments and related data.
Field Type Description commentable_meta CommentableMeta[] ID of the object the comment is attached to comments Comment[] Array of comments ordered according to sort ; cursor Cursor has_more boolean If there are more comments or replies available has_more_id number? included_comments Comment[] Related comments; e.g. parent comments and nested replies pinned_comments Comment[]? Pinned comments sort string one of the CommentSort types top_level_count number? Number of comments at the top level. Not returned for replies. total number? Total number of comments. Not retuned for replies. user_follow boolean is the current user watching the comment thread? user_votes number[] IDs of the comments in the bundle the current user has upvoted users UserCompact[] array of users related to the comments
CommentSort
Type Sort Fields new created_at (descending), id (descending) old created_at (ascending), id (ascending) top votes_count (descending), created_at (descending), id (descending)
Building cursor for comments listing
The returned response will be for comments after the specified sort fields.
For example, use last loaded comment for the fields value to load more comments. Also make sure to use same sort and parent_id values.
CommentableMeta
Metadata of the object that a comment is attached to.
Field Type Description id number the ID of the object title string display title type string the type of the object url string url of the object
CurrentUserAttributes
An object listing various related permissions and states for the current user, related to the object it is attached to.
BeatmapsetDiscussionPermissions
TODO: needs a better name.
Name Description can_destroy Can delete the discussion. can_reopen Can reopen the discussion. can_moderate_kudosu Can allow or deny kudosu. can_resolve Can resolve the discussion. vote_score Current vote given to the discussion.
ChatChannelUserAttributes
Name Type Description can_message boolean Can send messages to this channel. can_message_error string? Reason messages cannot be sent to this channel last_read_id number message_id of last message read.
Cursor
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.
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
osu!api open beta
Нет аккаунта?
osu!api open beta
I’ve had an API available for a while but until now it has been on a private on-request basis. In order to try and make developing third party services which expand and support osu!, I have added an API key setup and started to document the API.
Documentation will be expanded as I find time to do so! If anyone currently using the API is able to help expand the documentation then please do.
comentarinformal wrote:
Before I spam it with requests that might not exist, is there anything to get user’s information?
(Also, is there anything to login users from this page in other places?)
There is /api/get_user
Gonna write an entry with the information I have about it.
Is there a fair use limit? (e.g. no more than XX requests per day)
For get_user, I suppose there is a mode parameter for getting user information for Taiko, CtB and osu!mania? Or do I have to file an issue in GitHub? Nevermind, I found it, the parameter to add is called «m» I have edited the GitHub wiki.
Oh well. I have some questions:
Are only the beatmap and user endpoints available?
The parameter «since» in /get_beatmap how I need to pass the time on it? UTC or unix timestamp?
Do I need to pass the key on the wiki’s API too?
Edit: What the countX values mean? Number of beatmaps?
comentarinformal wrote:
Before I spam it with requests that might not exist, is there anything to get user’s information?
(Also, is there anything to login users from this page in other places?)
I guess I’ll update my userbar too when I find some time.
Damnae wrote:
I guess I’ll update my userbar too when I find some time.
I registered it for osu!userbar, but I also use it for my «Big ugly white signature», they are not on the same webserver, but it works fine
I belive only you and peppy can see the name you used, too.
(Yes I took my lazyness off, it was not that long to update ^^)
@Repflez: I tried using your API-powered signature and I get something weird.
Since I only aim for SS, I have 100% Accuracy all the time, and the Accuracy display is weird.
(I now know that despite having all-SS records, the note hit count for getting 50s and 100s are still counted all the time )
Winshley wrote:
@Repflez: I tried using your API-powered signature and I get something weird.
Since I only aim for SS, I have 100% Accuracy all the time, and the Accuracy display is weird.
(I now know that despite having all-SS records, the note hit count for getting 50s and 100s are still counted all the time )
So that’s what the CountX values mean. Thanks for that. I already went and changed the accuracy to show a centered «100% Accuracy» if it’s 100. Forget that. I ditched the bar on it and used the extra space for showing the PP.
(I love how the 300 count ended overlaping the border)
Repflez wrote:
So that’s what the CountX values mean. Thanks for that.
Yeah. At first I thought that there was something wrong with the API showing 50s and 100s despite having 100% Accuracy, until I actually calculated all 300s + 100s + 50s = «Total Hits» on our profile.
About the 300 overlap though, it does need some fix:
When you reached 10 millions of 300 hits, the last number is cut off. Cookiezi has 17 millions of 300 hits.
I’m not sure how the level bar breaking happens though. I was thinking that it probably because I don’t have any ranked score on osu!mania?
[Archived] getting osu! api token
Нет аккаунта?
[Archived] getting osu! api token
here is the website I am currently using this for https://osu-api-crap.minecreeper0913.repl.co
well since the project I am using is all python and not javascript I am using a new tab browser to just test it and so far the code I am using is
url = («https://osu.ppy.sh/oauth/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=%s» % (code))
the &code=%s is basically just grabbing the code that has been given back by oauth and using that as the url, when I am testing it though I am actually using my code
Never share your client secret, it’s secret for a reason. I would recommend resetting it ASAP.
Are you just typing that URL into your browser or are you actually sending it as a post request with whatever python code you have? Typing the URL into your browser won’t work.
The token endpoint takes the parameters in the body of the request, not as query parameters. You are also missing some parameters, like redirect_uri and grant_type.
If you are using python’s requests library, you can do something like this:
Might have some syntax errors because I wrote that from memory and didn’t check anything in an IDE or by running it.
You can try without specifying the content type in your headers, it might work without it. Very simply, the content type header describes what type of content or data is being sent. As far as I recall, the server is expecting that content type but I could be wrong.
now starting to realize that I might have done this a bit wrong, this is the first time I have used an API for something so everything I am doing is new to me.
So the first thing that is happening is that you press the login to link your osu API to the website, then it grabs your code and redirects you to the home website with the code in the url for example http://www.website.com/code=j9838r9y82g9438gh8243hg384hg, and it is supposed to use that, but when in testing it just returns favicon.ico, and I don’t know what that is or means so I might have to change my get request, another issue is but how would I make it get that auth code?
I don’t know anything about the project you are working on, so unfortunately I don’t think I can really answer any of the questions you’re asking.
I don’t know what you mean by a favicon being returned and I also don’t know what you are using the handle the backend of your site, so I can’t specifically tell you how to grab the code. Whatever you are using should have some way of getting query parameters from the URL.
Oauth2 is a very standardized and should be nearly the same everywhere that uses it. osu! is no exception. I would highly recommend looking up and reading about the authorization code flow that you are trying to use here. There should be a ton of resources and maybe a few code examples as well.
There might not be any videos specific to osu!’s API, but there are definitely Oauth2 tutorial videos and examples out there in probably every programming language, which is what you are dealing with right now.
For example, here is a video I found after a quick Google search that is using Python. I can’t fully comment on its quality since I just skimmed through it, but the general flow that the creator of the video goes over seems like it will at least cover how OAuth2 works in general, even if it’s not in the context of osu!’s API.
And even if you don’t really like reading, there are still some pretty good resources you can use that might help in addition to watching a video. Like this and this for example. Again, I’ve only skimmed through these, but they also seem to be pretty good.
here is the code I use:
NOTE I did not actually use SECRET as the secret I have it as SECRET because its secret
/beatmapsets/events
/beatmapsets//favourites
/chat/presence
/matches
/matches//rooms//rooms//users//rooms//users//rooms//leaderboard
/rooms//playlist//scores
/rooms//playlist//scores//reports
/rooms
/rooms//seasonal-backgrounds
/scores///download
/scores///beatmapsets/search//beatmapsets/lookup
/beatmapsets//friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
Similar to Get User but with authenticated user (token owner) as user id.
Response format
Additionally, statistics_rulesets is included, containing statistics for all rulesets.
Get User Kudosu
Returns kudosu history.
Response format
Get User Scores
This endpoint returns the scores of specified user.
Response format
Array of Score. Following attributes are included in the response object when applicable.
Get User Beatmaps
Returns the beatmaps of specified user.
Type Notes favourite graveyard loved most_played pending Previously unranked ranked Previously ranked_and_approved
Response format
Array of BeatmapPlaycount when type is most_played ; array of Beatmapset, otherwise.
Get User Recent Activity
Returns recent activity.
Response format
Get User
This endpoint returns the detail of specified user.
Response format
Returns User object. The following optional attributes on UserCompact are included:
Get Users
Returns list of users.
Response format
Field Type Description users UserCompact[] Includes: country, cover, groups, statistics_rulesets.
Get Wiki Page
The wiki article or image data.
Response Format
Notification Websocket
Connection
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:
Field Type Description event string See below
logout event
Server will disconnect session after sending this event so don’t try to reconnect.
Field Type Description event string logout
new event
New notification. See Notification object for notification types.
Field Type Description event string new data Notification
read event
Notification has been read.
Field Type Description event string read ids number[] id of Notifications which are read
Object Structures
Beatmap
Represent a beatmap. This extends BeatmapCompact with additional attributes.
Field Type Description accuracy float ar float beatmapset_id integer bpm float? convert boolean count_circles integer count_sliders integer count_spinners integer cs float deleted_at Timestamp? drain float hit_length integer is_scoreable boolean last_updated Timestamp mode_int integer passcount integer playcount integer ranked integer See Rank status for list of possible values. url string
BeatmapCompact
Represent a beatmap.
Field Type Description beatmapset_id integer difficulty_rating float id integer mode GameMode status string See Rank status for list of possible values. total_length integer user_id integer version string
Field Type Description beatmapset Beatmapset|BeatmapsetCompact|null Beatmapset for Beatmap object, BeatmapsetCompact for BeatmapCompact object. null if the beatmap doesn’t have associated beatmapset (e.g. deleted). checksum string? failtimes Failtimes max_combo integer
Failtimes
All fields are optional but there’s always at least one field returned.
Field Type Description exit integer[]? Array of length 100. fail integer[]? Array of length 100.
BeatmapDifficultyAttributes
Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.
Field Type max_combo integer star_rating float
Field Type aim_difficulty float approach_rate float flashlight_difficulty float overall_difficulty float slider_factor float speed_difficulty float
taiko
Field Type stamina_difficulty float rhythm_difficulty float colour_difficulty float approach_rate float great_hit_window float
fruits
mania
Field Type great_hit_window float score_multiplier float
BeatmapPlaycount
Represent the playcount of a beatmap.
Field Type Description beatmap_id number beatmap BeatmapCompact? beatmapset BeatmapsetCompact? count number
BeatmapScores
Field Type Description scores Score[] The list of top scores for the beatmap in descending order. userScore BeatmapUserScore? The score of the current user. This is not returned if the current user does not have a score. Note: will be moved to user_score in the future
BeatmapUserScore
Field Type Description position number The position of the score within the requested beatmap ranking. score Score The details of the score.
Beatmapset
Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.
Field Type Description availability.download_disabled boolean availability.more_information string? bpm float can_be_hyped boolean creator string Username of the mapper at the time of beatmapset creation. discussion_locked boolean hype.current integer hype.required integer is_scoreable boolean last_updated Timestamp legacy_thread_url string? nominations.current integer nominations.required integer ranked integer See Rank status for list of possible values. ranked_date Timestamp? source string storyboard boolean submitted_date Timestamp? tags string
The following attributes are always included as well:
Field has_favourited
BeatmapsetCompact
Represents a beatmapset.
Field Type Description artist string artist_unicode string covers Covers creator string favourite_count number id number nsfw boolean play_count number preview_url string source string status string title string title_unicode string user_id number video boolean
Those fields are optional.
Field Type Description beatmaps Beatmap[] converts current_user_attributes description discussions events genre has_favourited boolean language nominations ratings recent_favourites related_users user
Covers
Field Type cover string cover@2x string card string card@2x string list string list@2x string slimcover string slimcover@2x string
Rank status
The possible values are denoted either as integer or string.
Integer String -2 graveyard -1 wip 0 pending 1 ranked 2 approved 3 qualified 4 loved
BeatmapsetDiscussion
Represents a Beatmapset modding discussion.
Field Type Description beatmap BeatmapCompact? beatmap_id number? beatmapset BeatmapsetCompact? beatmapset_id number can_be_resolved boolean can_grant_kudosu boolean created_at Timestamp current_user_attributes CurrentUserAttributes deleted_at Timestamp? deleted_by_id number? id number kudosu_denied boolean last_post_at Timestamp message_type MessageType parent_id number? posts BeatmapsetDiscussionPost[]? resolved boolean starting_post BeatmapsetDiscussionPost? timestamp number? updated_at Timestamp user_id number
MessageType
Name Description hype mapper_note praise problem review suggestion
BeatmapsetDiscussionPost
Field Type Description beatmapset_discussion_id number created_at Timestamp deleted_at Timestamp? deleted_by_id number? id number last_editor_id number? message string system boolean updated_at Timestamp user_id number
BeatmapsetDiscussionVote
Field Type Description beatmapset_discussion_id number created_at Timestamp id number score number updated_at Timestamp user_id number
Build
Field Type created_at Timestamp display_version string id number update_stream UpdateStream? users number version string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes changelog_entries ChangelogEntry[] If the build has no changelog entries, a placeholder is generated. versions Versions
Versions
ChangelogEntry
Field Type category string created_at Timestamp? github_pull_request_id number? github_url string? id number? major boolean repository string? title string? type string url string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes github_user GithubUser If the changelog entry has no GitHub user, a placeholder is generated. message string? Entry message in Markdown format. Embedded HTML is allowed. message_html string? Entry message in HTML format.
ChatChannel
Represents an individual chat «channel» in the game.
Channel Types
Type Permission Check for Joining/Messaging PUBLIC PRIVATE is player in the allowed groups? (channel.allowed_groups) MULTIPLAYER is player currently in the mp game? SPECTATOR TEMPORARY deprecated PM see below (user_channels) GROUP is player in channel? (user_channels)
For PMs, two factors are taken into account:
ChatMessage
Represents an individual Message within a ChatChannel.
Field Type Description message_id number unique identifier for message sender_id number user_id of the sender channel_id number channel_id of where the message was sent timestamp string when the message was sent, ISO-8601 content string message content is_action boolean was this an action? i.e. /me dances sender UserCompact embedded UserCompact object to save additional api lookups
Comment
Represents an single comment.
Field Type Description commentable_id number ID of the object the comment is attached to commentable_type string type of object the comment is attached to created_at string ISO 8601 date deleted_at string? ISO 8601 date if the comment was deleted; null, otherwise edited_at string? ISO 8601 date if the comment was edited; null, otherwise edited_by_id number? user id of the user that edited the post; null, otherwise id number the ID of the comment legacy_name string? username displayed on legacy comments message string? markdown of the comment’s content message_html string? html version of the comment’s content parent_id number? ID of the comment’s parent pinned boolean Pin status of the comment replies_count number number of replies to the comment updated_at string ISO 8601 date user_id number user ID of the poster votes_count number number of votes
CommentBundle
Comments and related data.
Field Type Description commentable_meta CommentableMeta[] ID of the object the comment is attached to comments Comment[] Array of comments ordered according to sort ; cursor Cursor has_more boolean If there are more comments or replies available has_more_id number? included_comments Comment[] Related comments; e.g. parent comments and nested replies pinned_comments Comment[]? Pinned comments sort string one of the CommentSort types top_level_count number? Number of comments at the top level. Not returned for replies. total number? Total number of comments. Not retuned for replies. user_follow boolean is the current user watching the comment thread? user_votes number[] IDs of the comments in the bundle the current user has upvoted users UserCompact[] array of users related to the comments
CommentSort
Type Sort Fields new created_at (descending), id (descending) old created_at (ascending), id (ascending) top votes_count (descending), created_at (descending), id (descending)
Building cursor for comments listing
The returned response will be for comments after the specified sort fields.
For example, use last loaded comment for the fields value to load more comments. Also make sure to use same sort and parent_id values.
CommentableMeta
Metadata of the object that a comment is attached to.
Field Type Description id number the ID of the object title string display title type string the type of the object url string url of the object
CurrentUserAttributes
An object listing various related permissions and states for the current user, related to the object it is attached to.
BeatmapsetDiscussionPermissions
TODO: needs a better name.
Name Description can_destroy Can delete the discussion. can_reopen Can reopen the discussion. can_moderate_kudosu Can allow or deny kudosu. can_resolve Can resolve the discussion. vote_score Current vote given to the discussion.
ChatChannelUserAttributes
Name Type Description can_message boolean Can send messages to this channel. can_message_error string? Reason messages cannot be sent to this channel last_read_id number message_id of last message read.
Cursor
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.
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
osu!api open beta
Нет аккаунта?
osu!api open beta
I’ve had an API available for a while but until now it has been on a private on-request basis. In order to try and make developing third party services which expand and support osu!, I have added an API key setup and started to document the API.
Documentation will be expanded as I find time to do so! If anyone currently using the API is able to help expand the documentation then please do.
comentarinformal wrote:
Before I spam it with requests that might not exist, is there anything to get user’s information?
(Also, is there anything to login users from this page in other places?)
There is /api/get_user
Gonna write an entry with the information I have about it.
Is there a fair use limit? (e.g. no more than XX requests per day)
For get_user, I suppose there is a mode parameter for getting user information for Taiko, CtB and osu!mania? Or do I have to file an issue in GitHub? Nevermind, I found it, the parameter to add is called «m» I have edited the GitHub wiki.
Oh well. I have some questions:
Are only the beatmap and user endpoints available?
The parameter «since» in /get_beatmap how I need to pass the time on it? UTC or unix timestamp?
Do I need to pass the key on the wiki’s API too?
Edit: What the countX values mean? Number of beatmaps?
comentarinformal wrote:
Before I spam it with requests that might not exist, is there anything to get user’s information?
(Also, is there anything to login users from this page in other places?)
I guess I’ll update my userbar too when I find some time.
Damnae wrote:
I guess I’ll update my userbar too when I find some time.
I registered it for osu!userbar, but I also use it for my «Big ugly white signature», they are not on the same webserver, but it works fine
I belive only you and peppy can see the name you used, too.
(Yes I took my lazyness off, it was not that long to update ^^)
@Repflez: I tried using your API-powered signature and I get something weird.
Since I only aim for SS, I have 100% Accuracy all the time, and the Accuracy display is weird.
(I now know that despite having all-SS records, the note hit count for getting 50s and 100s are still counted all the time )
Winshley wrote:
@Repflez: I tried using your API-powered signature and I get something weird.
Since I only aim for SS, I have 100% Accuracy all the time, and the Accuracy display is weird.
(I now know that despite having all-SS records, the note hit count for getting 50s and 100s are still counted all the time )
So that’s what the CountX values mean. Thanks for that. I already went and changed the accuracy to show a centered «100% Accuracy» if it’s 100. Forget that. I ditched the bar on it and used the extra space for showing the PP.
(I love how the 300 count ended overlaping the border)
Repflez wrote:
So that’s what the CountX values mean. Thanks for that.
Yeah. At first I thought that there was something wrong with the API showing 50s and 100s despite having 100% Accuracy, until I actually calculated all 300s + 100s + 50s = «Total Hits» on our profile.
About the 300 overlap though, it does need some fix:
When you reached 10 millions of 300 hits, the last number is cut off. Cookiezi has 17 millions of 300 hits.
I’m not sure how the level bar breaking happens though. I was thinking that it probably because I don’t have any ranked score on osu!mania?
[Archived] getting osu! api token
Нет аккаунта?
[Archived] getting osu! api token
here is the website I am currently using this for https://osu-api-crap.minecreeper0913.repl.co
well since the project I am using is all python and not javascript I am using a new tab browser to just test it and so far the code I am using is
url = («https://osu.ppy.sh/oauth/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=%s» % (code))
the &code=%s is basically just grabbing the code that has been given back by oauth and using that as the url, when I am testing it though I am actually using my code
Never share your client secret, it’s secret for a reason. I would recommend resetting it ASAP.
Are you just typing that URL into your browser or are you actually sending it as a post request with whatever python code you have? Typing the URL into your browser won’t work.
The token endpoint takes the parameters in the body of the request, not as query parameters. You are also missing some parameters, like redirect_uri and grant_type.
If you are using python’s requests library, you can do something like this:
Might have some syntax errors because I wrote that from memory and didn’t check anything in an IDE or by running it.
You can try without specifying the content type in your headers, it might work without it. Very simply, the content type header describes what type of content or data is being sent. As far as I recall, the server is expecting that content type but I could be wrong.
now starting to realize that I might have done this a bit wrong, this is the first time I have used an API for something so everything I am doing is new to me.
So the first thing that is happening is that you press the login to link your osu API to the website, then it grabs your code and redirects you to the home website with the code in the url for example http://www.website.com/code=j9838r9y82g9438gh8243hg384hg, and it is supposed to use that, but when in testing it just returns favicon.ico, and I don’t know what that is or means so I might have to change my get request, another issue is but how would I make it get that auth code?
I don’t know anything about the project you are working on, so unfortunately I don’t think I can really answer any of the questions you’re asking.
I don’t know what you mean by a favicon being returned and I also don’t know what you are using the handle the backend of your site, so I can’t specifically tell you how to grab the code. Whatever you are using should have some way of getting query parameters from the URL.
Oauth2 is a very standardized and should be nearly the same everywhere that uses it. osu! is no exception. I would highly recommend looking up and reading about the authorization code flow that you are trying to use here. There should be a ton of resources and maybe a few code examples as well.
There might not be any videos specific to osu!’s API, but there are definitely Oauth2 tutorial videos and examples out there in probably every programming language, which is what you are dealing with right now.
For example, here is a video I found after a quick Google search that is using Python. I can’t fully comment on its quality since I just skimmed through it, but the general flow that the creator of the video goes over seems like it will at least cover how OAuth2 works in general, even if it’s not in the context of osu!’s API.
And even if you don’t really like reading, there are still some pretty good resources you can use that might help in addition to watching a video. Like this and this for example. Again, I’ve only skimmed through these, but they also seem to be pretty good.
here is the code I use:
NOTE I did not actually use SECRET as the secret I have it as SECRET because its secret
/rooms//users//rooms//users//rooms//leaderboard
/rooms//playlist//scores
/rooms//playlist//scores//reports
/rooms
/rooms//seasonal-backgrounds
/scores///download
/scores///beatmapsets/search//beatmapsets/lookup
/beatmapsets//friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
Similar to Get User but with authenticated user (token owner) as user id.
Response format
Additionally, statistics_rulesets is included, containing statistics for all rulesets.
Get User Kudosu
Returns kudosu history.
Response format
Get User Scores
This endpoint returns the scores of specified user.
Response format
Array of Score. Following attributes are included in the response object when applicable.
Get User Beatmaps
Returns the beatmaps of specified user.
Type Notes favourite graveyard loved most_played pending Previously unranked ranked Previously ranked_and_approved
Response format
Array of BeatmapPlaycount when type is most_played ; array of Beatmapset, otherwise.
Get User Recent Activity
Returns recent activity.
Response format
Get User
This endpoint returns the detail of specified user.
Response format
Returns User object. The following optional attributes on UserCompact are included:
Get Users
Returns list of users.
Response format
Field Type Description users UserCompact[] Includes: country, cover, groups, statistics_rulesets.
Get Wiki Page
The wiki article or image data.
Response Format
Notification Websocket
Connection
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:
Field Type Description event string See below
logout event
Server will disconnect session after sending this event so don’t try to reconnect.
Field Type Description event string logout
new event
New notification. See Notification object for notification types.
Field Type Description event string new data Notification
read event
Notification has been read.
Field Type Description event string read ids number[] id of Notifications which are read
Object Structures
Beatmap
Represent a beatmap. This extends BeatmapCompact with additional attributes.
Field Type Description accuracy float ar float beatmapset_id integer bpm float? convert boolean count_circles integer count_sliders integer count_spinners integer cs float deleted_at Timestamp? drain float hit_length integer is_scoreable boolean last_updated Timestamp mode_int integer passcount integer playcount integer ranked integer See Rank status for list of possible values. url string
BeatmapCompact
Represent a beatmap.
Field Type Description beatmapset_id integer difficulty_rating float id integer mode GameMode status string See Rank status for list of possible values. total_length integer user_id integer version string
Field Type Description beatmapset Beatmapset|BeatmapsetCompact|null Beatmapset for Beatmap object, BeatmapsetCompact for BeatmapCompact object. null if the beatmap doesn’t have associated beatmapset (e.g. deleted). checksum string? failtimes Failtimes max_combo integer
Failtimes
All fields are optional but there’s always at least one field returned.
Field Type Description exit integer[]? Array of length 100. fail integer[]? Array of length 100.
BeatmapDifficultyAttributes
Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.
Field Type max_combo integer star_rating float
Field Type aim_difficulty float approach_rate float flashlight_difficulty float overall_difficulty float slider_factor float speed_difficulty float
taiko
Field Type stamina_difficulty float rhythm_difficulty float colour_difficulty float approach_rate float great_hit_window float
fruits
mania
Field Type great_hit_window float score_multiplier float
BeatmapPlaycount
Represent the playcount of a beatmap.
Field Type Description beatmap_id number beatmap BeatmapCompact? beatmapset BeatmapsetCompact? count number
BeatmapScores
Field Type Description scores Score[] The list of top scores for the beatmap in descending order. userScore BeatmapUserScore? The score of the current user. This is not returned if the current user does not have a score. Note: will be moved to user_score in the future
BeatmapUserScore
Field Type Description position number The position of the score within the requested beatmap ranking. score Score The details of the score.
Beatmapset
Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.
Field Type Description availability.download_disabled boolean availability.more_information string? bpm float can_be_hyped boolean creator string Username of the mapper at the time of beatmapset creation. discussion_locked boolean hype.current integer hype.required integer is_scoreable boolean last_updated Timestamp legacy_thread_url string? nominations.current integer nominations.required integer ranked integer See Rank status for list of possible values. ranked_date Timestamp? source string storyboard boolean submitted_date Timestamp? tags string
The following attributes are always included as well:
Field has_favourited
BeatmapsetCompact
Represents a beatmapset.
Field Type Description artist string artist_unicode string covers Covers creator string favourite_count number id number nsfw boolean play_count number preview_url string source string status string title string title_unicode string user_id number video boolean
Those fields are optional.
Field Type Description beatmaps Beatmap[] converts current_user_attributes description discussions events genre has_favourited boolean language nominations ratings recent_favourites related_users user
Covers
Field Type cover string cover@2x string card string card@2x string list string list@2x string slimcover string slimcover@2x string
Rank status
The possible values are denoted either as integer or string.
Integer String -2 graveyard -1 wip 0 pending 1 ranked 2 approved 3 qualified 4 loved
BeatmapsetDiscussion
Represents a Beatmapset modding discussion.
Field Type Description beatmap BeatmapCompact? beatmap_id number? beatmapset BeatmapsetCompact? beatmapset_id number can_be_resolved boolean can_grant_kudosu boolean created_at Timestamp current_user_attributes CurrentUserAttributes deleted_at Timestamp? deleted_by_id number? id number kudosu_denied boolean last_post_at Timestamp message_type MessageType parent_id number? posts BeatmapsetDiscussionPost[]? resolved boolean starting_post BeatmapsetDiscussionPost? timestamp number? updated_at Timestamp user_id number
MessageType
Name Description hype mapper_note praise problem review suggestion
BeatmapsetDiscussionPost
Field Type Description beatmapset_discussion_id number created_at Timestamp deleted_at Timestamp? deleted_by_id number? id number last_editor_id number? message string system boolean updated_at Timestamp user_id number
BeatmapsetDiscussionVote
Field Type Description beatmapset_discussion_id number created_at Timestamp id number score number updated_at Timestamp user_id number
Build
Field Type created_at Timestamp display_version string id number update_stream UpdateStream? users number version string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes changelog_entries ChangelogEntry[] If the build has no changelog entries, a placeholder is generated. versions Versions
Versions
ChangelogEntry
Field Type category string created_at Timestamp? github_pull_request_id number? github_url string? id number? major boolean repository string? title string? type string url string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes github_user GithubUser If the changelog entry has no GitHub user, a placeholder is generated. message string? Entry message in Markdown format. Embedded HTML is allowed. message_html string? Entry message in HTML format.
ChatChannel
Represents an individual chat «channel» in the game.
Channel Types
Type Permission Check for Joining/Messaging PUBLIC PRIVATE is player in the allowed groups? (channel.allowed_groups) MULTIPLAYER is player currently in the mp game? SPECTATOR TEMPORARY deprecated PM see below (user_channels) GROUP is player in channel? (user_channels)
For PMs, two factors are taken into account:
ChatMessage
Represents an individual Message within a ChatChannel.
Field Type Description message_id number unique identifier for message sender_id number user_id of the sender channel_id number channel_id of where the message was sent timestamp string when the message was sent, ISO-8601 content string message content is_action boolean was this an action? i.e. /me dances sender UserCompact embedded UserCompact object to save additional api lookups
Comment
Represents an single comment.
Field Type Description commentable_id number ID of the object the comment is attached to commentable_type string type of object the comment is attached to created_at string ISO 8601 date deleted_at string? ISO 8601 date if the comment was deleted; null, otherwise edited_at string? ISO 8601 date if the comment was edited; null, otherwise edited_by_id number? user id of the user that edited the post; null, otherwise id number the ID of the comment legacy_name string? username displayed on legacy comments message string? markdown of the comment’s content message_html string? html version of the comment’s content parent_id number? ID of the comment’s parent pinned boolean Pin status of the comment replies_count number number of replies to the comment updated_at string ISO 8601 date user_id number user ID of the poster votes_count number number of votes
CommentBundle
Comments and related data.
Field Type Description commentable_meta CommentableMeta[] ID of the object the comment is attached to comments Comment[] Array of comments ordered according to sort ; cursor Cursor has_more boolean If there are more comments or replies available has_more_id number? included_comments Comment[] Related comments; e.g. parent comments and nested replies pinned_comments Comment[]? Pinned comments sort string one of the CommentSort types top_level_count number? Number of comments at the top level. Not returned for replies. total number? Total number of comments. Not retuned for replies. user_follow boolean is the current user watching the comment thread? user_votes number[] IDs of the comments in the bundle the current user has upvoted users UserCompact[] array of users related to the comments
CommentSort
Type Sort Fields new created_at (descending), id (descending) old created_at (ascending), id (ascending) top votes_count (descending), created_at (descending), id (descending)
Building cursor for comments listing
The returned response will be for comments after the specified sort fields.
For example, use last loaded comment for the fields value to load more comments. Also make sure to use same sort and parent_id values.
CommentableMeta
Metadata of the object that a comment is attached to.
Field Type Description id number the ID of the object title string display title type string the type of the object url string url of the object
CurrentUserAttributes
An object listing various related permissions and states for the current user, related to the object it is attached to.
BeatmapsetDiscussionPermissions
TODO: needs a better name.
Name Description can_destroy Can delete the discussion. can_reopen Can reopen the discussion. can_moderate_kudosu Can allow or deny kudosu. can_resolve Can resolve the discussion. vote_score Current vote given to the discussion.
ChatChannelUserAttributes
Name Type Description can_message boolean Can send messages to this channel. can_message_error string? Reason messages cannot be sent to this channel last_read_id number message_id of last message read.
Cursor
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.
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
osu!api open beta
Нет аккаунта?
osu!api open beta
I’ve had an API available for a while but until now it has been on a private on-request basis. In order to try and make developing third party services which expand and support osu!, I have added an API key setup and started to document the API.
Documentation will be expanded as I find time to do so! If anyone currently using the API is able to help expand the documentation then please do.
comentarinformal wrote:
Before I spam it with requests that might not exist, is there anything to get user’s information?
(Also, is there anything to login users from this page in other places?)
There is /api/get_user
Gonna write an entry with the information I have about it.
Is there a fair use limit? (e.g. no more than XX requests per day)
For get_user, I suppose there is a mode parameter for getting user information for Taiko, CtB and osu!mania? Or do I have to file an issue in GitHub? Nevermind, I found it, the parameter to add is called «m» I have edited the GitHub wiki.
Oh well. I have some questions:
Are only the beatmap and user endpoints available?
The parameter «since» in /get_beatmap how I need to pass the time on it? UTC or unix timestamp?
Do I need to pass the key on the wiki’s API too?
Edit: What the countX values mean? Number of beatmaps?
comentarinformal wrote:
Before I spam it with requests that might not exist, is there anything to get user’s information?
(Also, is there anything to login users from this page in other places?)
I guess I’ll update my userbar too when I find some time.
Damnae wrote:
I guess I’ll update my userbar too when I find some time.
I registered it for osu!userbar, but I also use it for my «Big ugly white signature», they are not on the same webserver, but it works fine
I belive only you and peppy can see the name you used, too.
(Yes I took my lazyness off, it was not that long to update ^^)
@Repflez: I tried using your API-powered signature and I get something weird.
Since I only aim for SS, I have 100% Accuracy all the time, and the Accuracy display is weird.
(I now know that despite having all-SS records, the note hit count for getting 50s and 100s are still counted all the time )
Winshley wrote:
@Repflez: I tried using your API-powered signature and I get something weird.
Since I only aim for SS, I have 100% Accuracy all the time, and the Accuracy display is weird.
(I now know that despite having all-SS records, the note hit count for getting 50s and 100s are still counted all the time )
So that’s what the CountX values mean. Thanks for that. I already went and changed the accuracy to show a centered «100% Accuracy» if it’s 100. Forget that. I ditched the bar on it and used the extra space for showing the PP.
(I love how the 300 count ended overlaping the border)
Repflez wrote:
So that’s what the CountX values mean. Thanks for that.
Yeah. At first I thought that there was something wrong with the API showing 50s and 100s despite having 100% Accuracy, until I actually calculated all 300s + 100s + 50s = «Total Hits» on our profile.
About the 300 overlap though, it does need some fix:
When you reached 10 millions of 300 hits, the last number is cut off. Cookiezi has 17 millions of 300 hits.
I’m not sure how the level bar breaking happens though. I was thinking that it probably because I don’t have any ranked score on osu!mania?
[Archived] getting osu! api token
Нет аккаунта?
[Archived] getting osu! api token
here is the website I am currently using this for https://osu-api-crap.minecreeper0913.repl.co
well since the project I am using is all python and not javascript I am using a new tab browser to just test it and so far the code I am using is
url = («https://osu.ppy.sh/oauth/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=%s» % (code))
the &code=%s is basically just grabbing the code that has been given back by oauth and using that as the url, when I am testing it though I am actually using my code
Never share your client secret, it’s secret for a reason. I would recommend resetting it ASAP.
Are you just typing that URL into your browser or are you actually sending it as a post request with whatever python code you have? Typing the URL into your browser won’t work.
The token endpoint takes the parameters in the body of the request, not as query parameters. You are also missing some parameters, like redirect_uri and grant_type.
If you are using python’s requests library, you can do something like this:
Might have some syntax errors because I wrote that from memory and didn’t check anything in an IDE or by running it.
You can try without specifying the content type in your headers, it might work without it. Very simply, the content type header describes what type of content or data is being sent. As far as I recall, the server is expecting that content type but I could be wrong.
now starting to realize that I might have done this a bit wrong, this is the first time I have used an API for something so everything I am doing is new to me.
So the first thing that is happening is that you press the login to link your osu API to the website, then it grabs your code and redirects you to the home website with the code in the url for example http://www.website.com/code=j9838r9y82g9438gh8243hg384hg, and it is supposed to use that, but when in testing it just returns favicon.ico, and I don’t know what that is or means so I might have to change my get request, another issue is but how would I make it get that auth code?
I don’t know anything about the project you are working on, so unfortunately I don’t think I can really answer any of the questions you’re asking.
I don’t know what you mean by a favicon being returned and I also don’t know what you are using the handle the backend of your site, so I can’t specifically tell you how to grab the code. Whatever you are using should have some way of getting query parameters from the URL.
Oauth2 is a very standardized and should be nearly the same everywhere that uses it. osu! is no exception. I would highly recommend looking up and reading about the authorization code flow that you are trying to use here. There should be a ton of resources and maybe a few code examples as well.
There might not be any videos specific to osu!’s API, but there are definitely Oauth2 tutorial videos and examples out there in probably every programming language, which is what you are dealing with right now.
For example, here is a video I found after a quick Google search that is using Python. I can’t fully comment on its quality since I just skimmed through it, but the general flow that the creator of the video goes over seems like it will at least cover how OAuth2 works in general, even if it’s not in the context of osu!’s API.
And even if you don’t really like reading, there are still some pretty good resources you can use that might help in addition to watching a video. Like this and this for example. Again, I’ve only skimmed through these, but they also seem to be pretty good.
here is the code I use:
NOTE I did not actually use SECRET as the secret I have it as SECRET because its secret
/rooms//users//rooms//leaderboard
/rooms//playlist//scores
/rooms//playlist//scores//reports
/rooms
/rooms//seasonal-backgrounds
/scores///download
/scores///beatmapsets/search//beatmapsets/lookup
/beatmapsets//friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
Similar to Get User but with authenticated user (token owner) as user id.
Response format
Additionally, statistics_rulesets is included, containing statistics for all rulesets.
Get User Kudosu
Returns kudosu history.
Response format
Get User Scores
This endpoint returns the scores of specified user.
Response format
Array of Score. Following attributes are included in the response object when applicable.
Get User Beatmaps
Returns the beatmaps of specified user.
Type Notes favourite graveyard loved most_played pending Previously unranked ranked Previously ranked_and_approved
Response format
Array of BeatmapPlaycount when type is most_played ; array of Beatmapset, otherwise.
Get User Recent Activity
Returns recent activity.
Response format
Get User
This endpoint returns the detail of specified user.
Response format
Returns User object. The following optional attributes on UserCompact are included:
Get Users
Returns list of users.
Response format
Field Type Description users UserCompact[] Includes: country, cover, groups, statistics_rulesets.
Get Wiki Page
The wiki article or image data.
Response Format
Notification Websocket
Connection
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:
Field Type Description event string See below
logout event
Server will disconnect session after sending this event so don’t try to reconnect.
Field Type Description event string logout
new event
New notification. See Notification object for notification types.
Field Type Description event string new data Notification
read event
Notification has been read.
Field Type Description event string read ids number[] id of Notifications which are read
Object Structures
Beatmap
Represent a beatmap. This extends BeatmapCompact with additional attributes.
Field Type Description accuracy float ar float beatmapset_id integer bpm float? convert boolean count_circles integer count_sliders integer count_spinners integer cs float deleted_at Timestamp? drain float hit_length integer is_scoreable boolean last_updated Timestamp mode_int integer passcount integer playcount integer ranked integer See Rank status for list of possible values. url string
BeatmapCompact
Represent a beatmap.
Field Type Description beatmapset_id integer difficulty_rating float id integer mode GameMode status string See Rank status for list of possible values. total_length integer user_id integer version string
Field Type Description beatmapset Beatmapset|BeatmapsetCompact|null Beatmapset for Beatmap object, BeatmapsetCompact for BeatmapCompact object. null if the beatmap doesn’t have associated beatmapset (e.g. deleted). checksum string? failtimes Failtimes max_combo integer
Failtimes
All fields are optional but there’s always at least one field returned.
Field Type Description exit integer[]? Array of length 100. fail integer[]? Array of length 100.
BeatmapDifficultyAttributes
Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.
Field Type max_combo integer star_rating float
Field Type aim_difficulty float approach_rate float flashlight_difficulty float overall_difficulty float slider_factor float speed_difficulty float
taiko
Field Type stamina_difficulty float rhythm_difficulty float colour_difficulty float approach_rate float great_hit_window float
fruits
mania
Field Type great_hit_window float score_multiplier float
BeatmapPlaycount
Represent the playcount of a beatmap.
Field Type Description beatmap_id number beatmap BeatmapCompact? beatmapset BeatmapsetCompact? count number
BeatmapScores
Field Type Description scores Score[] The list of top scores for the beatmap in descending order. userScore BeatmapUserScore? The score of the current user. This is not returned if the current user does not have a score. Note: will be moved to user_score in the future
BeatmapUserScore
Field Type Description position number The position of the score within the requested beatmap ranking. score Score The details of the score.
Beatmapset
Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.
Field Type Description availability.download_disabled boolean availability.more_information string? bpm float can_be_hyped boolean creator string Username of the mapper at the time of beatmapset creation. discussion_locked boolean hype.current integer hype.required integer is_scoreable boolean last_updated Timestamp legacy_thread_url string? nominations.current integer nominations.required integer ranked integer See Rank status for list of possible values. ranked_date Timestamp? source string storyboard boolean submitted_date Timestamp? tags string
The following attributes are always included as well:
Field has_favourited
BeatmapsetCompact
Represents a beatmapset.
Field Type Description artist string artist_unicode string covers Covers creator string favourite_count number id number nsfw boolean play_count number preview_url string source string status string title string title_unicode string user_id number video boolean
Those fields are optional.
Field Type Description beatmaps Beatmap[] converts current_user_attributes description discussions events genre has_favourited boolean language nominations ratings recent_favourites related_users user
Covers
Field Type cover string cover@2x string card string card@2x string list string list@2x string slimcover string slimcover@2x string
Rank status
The possible values are denoted either as integer or string.
Integer String -2 graveyard -1 wip 0 pending 1 ranked 2 approved 3 qualified 4 loved
BeatmapsetDiscussion
Represents a Beatmapset modding discussion.
Field Type Description beatmap BeatmapCompact? beatmap_id number? beatmapset BeatmapsetCompact? beatmapset_id number can_be_resolved boolean can_grant_kudosu boolean created_at Timestamp current_user_attributes CurrentUserAttributes deleted_at Timestamp? deleted_by_id number? id number kudosu_denied boolean last_post_at Timestamp message_type MessageType parent_id number? posts BeatmapsetDiscussionPost[]? resolved boolean starting_post BeatmapsetDiscussionPost? timestamp number? updated_at Timestamp user_id number
MessageType
Name Description hype mapper_note praise problem review suggestion
BeatmapsetDiscussionPost
Field Type Description beatmapset_discussion_id number created_at Timestamp deleted_at Timestamp? deleted_by_id number? id number last_editor_id number? message string system boolean updated_at Timestamp user_id number
BeatmapsetDiscussionVote
Field Type Description beatmapset_discussion_id number created_at Timestamp id number score number updated_at Timestamp user_id number
Build
Field Type created_at Timestamp display_version string id number update_stream UpdateStream? users number version string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes changelog_entries ChangelogEntry[] If the build has no changelog entries, a placeholder is generated. versions Versions
Versions
ChangelogEntry
Field Type category string created_at Timestamp? github_pull_request_id number? github_url string? id number? major boolean repository string? title string? type string url string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes github_user GithubUser If the changelog entry has no GitHub user, a placeholder is generated. message string? Entry message in Markdown format. Embedded HTML is allowed. message_html string? Entry message in HTML format.
ChatChannel
Represents an individual chat «channel» in the game.
Channel Types
Type Permission Check for Joining/Messaging PUBLIC PRIVATE is player in the allowed groups? (channel.allowed_groups) MULTIPLAYER is player currently in the mp game? SPECTATOR TEMPORARY deprecated PM see below (user_channels) GROUP is player in channel? (user_channels)
For PMs, two factors are taken into account:
ChatMessage
Represents an individual Message within a ChatChannel.
Field Type Description message_id number unique identifier for message sender_id number user_id of the sender channel_id number channel_id of where the message was sent timestamp string when the message was sent, ISO-8601 content string message content is_action boolean was this an action? i.e. /me dances sender UserCompact embedded UserCompact object to save additional api lookups
Comment
Represents an single comment.
Field Type Description commentable_id number ID of the object the comment is attached to commentable_type string type of object the comment is attached to created_at string ISO 8601 date deleted_at string? ISO 8601 date if the comment was deleted; null, otherwise edited_at string? ISO 8601 date if the comment was edited; null, otherwise edited_by_id number? user id of the user that edited the post; null, otherwise id number the ID of the comment legacy_name string? username displayed on legacy comments message string? markdown of the comment’s content message_html string? html version of the comment’s content parent_id number? ID of the comment’s parent pinned boolean Pin status of the comment replies_count number number of replies to the comment updated_at string ISO 8601 date user_id number user ID of the poster votes_count number number of votes
CommentBundle
Comments and related data.
Field Type Description commentable_meta CommentableMeta[] ID of the object the comment is attached to comments Comment[] Array of comments ordered according to sort ; cursor Cursor has_more boolean If there are more comments or replies available has_more_id number? included_comments Comment[] Related comments; e.g. parent comments and nested replies pinned_comments Comment[]? Pinned comments sort string one of the CommentSort types top_level_count number? Number of comments at the top level. Not returned for replies. total number? Total number of comments. Not retuned for replies. user_follow boolean is the current user watching the comment thread? user_votes number[] IDs of the comments in the bundle the current user has upvoted users UserCompact[] array of users related to the comments
CommentSort
Type Sort Fields new created_at (descending), id (descending) old created_at (ascending), id (ascending) top votes_count (descending), created_at (descending), id (descending)
Building cursor for comments listing
The returned response will be for comments after the specified sort fields.
For example, use last loaded comment for the fields value to load more comments. Also make sure to use same sort and parent_id values.
CommentableMeta
Metadata of the object that a comment is attached to.
Field Type Description id number the ID of the object title string display title type string the type of the object url string url of the object
CurrentUserAttributes
An object listing various related permissions and states for the current user, related to the object it is attached to.
BeatmapsetDiscussionPermissions
TODO: needs a better name.
Name Description can_destroy Can delete the discussion. can_reopen Can reopen the discussion. can_moderate_kudosu Can allow or deny kudosu. can_resolve Can resolve the discussion. vote_score Current vote given to the discussion.
ChatChannelUserAttributes
Name Type Description can_message boolean Can send messages to this channel. can_message_error string? Reason messages cannot be sent to this channel last_read_id number message_id of last message read.
Cursor
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.
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
osu!api open beta
Нет аккаунта?
osu!api open beta
I’ve had an API available for a while but until now it has been on a private on-request basis. In order to try and make developing third party services which expand and support osu!, I have added an API key setup and started to document the API.
Documentation will be expanded as I find time to do so! If anyone currently using the API is able to help expand the documentation then please do.
comentarinformal wrote:
Before I spam it with requests that might not exist, is there anything to get user’s information?
(Also, is there anything to login users from this page in other places?)
There is /api/get_user
Gonna write an entry with the information I have about it.
Is there a fair use limit? (e.g. no more than XX requests per day)
For get_user, I suppose there is a mode parameter for getting user information for Taiko, CtB and osu!mania? Or do I have to file an issue in GitHub? Nevermind, I found it, the parameter to add is called «m» I have edited the GitHub wiki.
Oh well. I have some questions:
Are only the beatmap and user endpoints available?
The parameter «since» in /get_beatmap how I need to pass the time on it? UTC or unix timestamp?
Do I need to pass the key on the wiki’s API too?
Edit: What the countX values mean? Number of beatmaps?
comentarinformal wrote:
Before I spam it with requests that might not exist, is there anything to get user’s information?
(Also, is there anything to login users from this page in other places?)
I guess I’ll update my userbar too when I find some time.
Damnae wrote:
I guess I’ll update my userbar too when I find some time.
I registered it for osu!userbar, but I also use it for my «Big ugly white signature», they are not on the same webserver, but it works fine
I belive only you and peppy can see the name you used, too.
(Yes I took my lazyness off, it was not that long to update ^^)
@Repflez: I tried using your API-powered signature and I get something weird.
Since I only aim for SS, I have 100% Accuracy all the time, and the Accuracy display is weird.
(I now know that despite having all-SS records, the note hit count for getting 50s and 100s are still counted all the time )
Winshley wrote:
@Repflez: I tried using your API-powered signature and I get something weird.
Since I only aim for SS, I have 100% Accuracy all the time, and the Accuracy display is weird.
(I now know that despite having all-SS records, the note hit count for getting 50s and 100s are still counted all the time )
So that’s what the CountX values mean. Thanks for that. I already went and changed the accuracy to show a centered «100% Accuracy» if it’s 100. Forget that. I ditched the bar on it and used the extra space for showing the PP.
(I love how the 300 count ended overlaping the border)
Repflez wrote:
So that’s what the CountX values mean. Thanks for that.
Yeah. At first I thought that there was something wrong with the API showing 50s and 100s despite having 100% Accuracy, until I actually calculated all 300s + 100s + 50s = «Total Hits» on our profile.
About the 300 overlap though, it does need some fix:
When you reached 10 millions of 300 hits, the last number is cut off. Cookiezi has 17 millions of 300 hits.
I’m not sure how the level bar breaking happens though. I was thinking that it probably because I don’t have any ranked score on osu!mania?
[Archived] getting osu! api token
Нет аккаунта?
[Archived] getting osu! api token
here is the website I am currently using this for https://osu-api-crap.minecreeper0913.repl.co
well since the project I am using is all python and not javascript I am using a new tab browser to just test it and so far the code I am using is
url = («https://osu.ppy.sh/oauth/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=%s» % (code))
the &code=%s is basically just grabbing the code that has been given back by oauth and using that as the url, when I am testing it though I am actually using my code
Never share your client secret, it’s secret for a reason. I would recommend resetting it ASAP.
Are you just typing that URL into your browser or are you actually sending it as a post request with whatever python code you have? Typing the URL into your browser won’t work.
The token endpoint takes the parameters in the body of the request, not as query parameters. You are also missing some parameters, like redirect_uri and grant_type.
If you are using python’s requests library, you can do something like this:
Might have some syntax errors because I wrote that from memory and didn’t check anything in an IDE or by running it.
You can try without specifying the content type in your headers, it might work without it. Very simply, the content type header describes what type of content or data is being sent. As far as I recall, the server is expecting that content type but I could be wrong.
now starting to realize that I might have done this a bit wrong, this is the first time I have used an API for something so everything I am doing is new to me.
So the first thing that is happening is that you press the login to link your osu API to the website, then it grabs your code and redirects you to the home website with the code in the url for example http://www.website.com/code=j9838r9y82g9438gh8243hg384hg, and it is supposed to use that, but when in testing it just returns favicon.ico, and I don’t know what that is or means so I might have to change my get request, another issue is but how would I make it get that auth code?
I don’t know anything about the project you are working on, so unfortunately I don’t think I can really answer any of the questions you’re asking.
I don’t know what you mean by a favicon being returned and I also don’t know what you are using the handle the backend of your site, so I can’t specifically tell you how to grab the code. Whatever you are using should have some way of getting query parameters from the URL.
Oauth2 is a very standardized and should be nearly the same everywhere that uses it. osu! is no exception. I would highly recommend looking up and reading about the authorization code flow that you are trying to use here. There should be a ton of resources and maybe a few code examples as well.
There might not be any videos specific to osu!’s API, but there are definitely Oauth2 tutorial videos and examples out there in probably every programming language, which is what you are dealing with right now.
For example, here is a video I found after a quick Google search that is using Python. I can’t fully comment on its quality since I just skimmed through it, but the general flow that the creator of the video goes over seems like it will at least cover how OAuth2 works in general, even if it’s not in the context of osu!’s API.
And even if you don’t really like reading, there are still some pretty good resources you can use that might help in addition to watching a video. Like this and this for example. Again, I’ve only skimmed through these, but they also seem to be pretty good.
here is the code I use:
NOTE I did not actually use SECRET as the secret I have it as SECRET because its secret
/rooms//leaderboard
/rooms//playlist//scores
/rooms//playlist//scores//reports
/rooms
/rooms//seasonal-backgrounds
/scores///download
/scores///beatmapsets/search//beatmapsets/lookup
/beatmapsets//friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
Similar to Get User but with authenticated user (token owner) as user id.
Response format
Additionally, statistics_rulesets is included, containing statistics for all rulesets.
Get User Kudosu
Returns kudosu history.
Response format
Get User Scores
This endpoint returns the scores of specified user.
Response format
Array of Score. Following attributes are included in the response object when applicable.
Get User Beatmaps
Returns the beatmaps of specified user.
Type Notes favourite graveyard loved most_played pending Previously unranked ranked Previously ranked_and_approved
Response format
Array of BeatmapPlaycount when type is most_played ; array of Beatmapset, otherwise.
Get User Recent Activity
Returns recent activity.
Response format
Get User
This endpoint returns the detail of specified user.
Response format
Returns User object. The following optional attributes on UserCompact are included:
Get Users
Returns list of users.
Response format
Field Type Description users UserCompact[] Includes: country, cover, groups, statistics_rulesets.
Get Wiki Page
The wiki article or image data.
Response Format
Notification Websocket
Connection
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:
Field Type Description event string See below
logout event
Server will disconnect session after sending this event so don’t try to reconnect.
Field Type Description event string logout
new event
New notification. See Notification object for notification types.
Field Type Description event string new data Notification
read event
Notification has been read.
Field Type Description event string read ids number[] id of Notifications which are read
Object Structures
Beatmap
Represent a beatmap. This extends BeatmapCompact with additional attributes.
Field Type Description accuracy float ar float beatmapset_id integer bpm float? convert boolean count_circles integer count_sliders integer count_spinners integer cs float deleted_at Timestamp? drain float hit_length integer is_scoreable boolean last_updated Timestamp mode_int integer passcount integer playcount integer ranked integer See Rank status for list of possible values. url string
BeatmapCompact
Represent a beatmap.
Field Type Description beatmapset_id integer difficulty_rating float id integer mode GameMode status string See Rank status for list of possible values. total_length integer user_id integer version string
Field Type Description beatmapset Beatmapset|BeatmapsetCompact|null Beatmapset for Beatmap object, BeatmapsetCompact for BeatmapCompact object. null if the beatmap doesn’t have associated beatmapset (e.g. deleted). checksum string? failtimes Failtimes max_combo integer
Failtimes
All fields are optional but there’s always at least one field returned.
Field Type Description exit integer[]? Array of length 100. fail integer[]? Array of length 100.
BeatmapDifficultyAttributes
Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.
Field Type max_combo integer star_rating float
Field Type aim_difficulty float approach_rate float flashlight_difficulty float overall_difficulty float slider_factor float speed_difficulty float
taiko
Field Type stamina_difficulty float rhythm_difficulty float colour_difficulty float approach_rate float great_hit_window float
fruits
mania
Field Type great_hit_window float score_multiplier float
BeatmapPlaycount
Represent the playcount of a beatmap.
Field Type Description beatmap_id number beatmap BeatmapCompact? beatmapset BeatmapsetCompact? count number
BeatmapScores
Field Type Description scores Score[] The list of top scores for the beatmap in descending order. userScore BeatmapUserScore? The score of the current user. This is not returned if the current user does not have a score. Note: will be moved to user_score in the future
BeatmapUserScore
Field Type Description position number The position of the score within the requested beatmap ranking. score Score The details of the score.
Beatmapset
Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.
Field Type Description availability.download_disabled boolean availability.more_information string? bpm float can_be_hyped boolean creator string Username of the mapper at the time of beatmapset creation. discussion_locked boolean hype.current integer hype.required integer is_scoreable boolean last_updated Timestamp legacy_thread_url string? nominations.current integer nominations.required integer ranked integer See Rank status for list of possible values. ranked_date Timestamp? source string storyboard boolean submitted_date Timestamp? tags string
The following attributes are always included as well:
Field has_favourited
BeatmapsetCompact
Represents a beatmapset.
Field Type Description artist string artist_unicode string covers Covers creator string favourite_count number id number nsfw boolean play_count number preview_url string source string status string title string title_unicode string user_id number video boolean
Those fields are optional.
Field Type Description beatmaps Beatmap[] converts current_user_attributes description discussions events genre has_favourited boolean language nominations ratings recent_favourites related_users user
Covers
Field Type cover string cover@2x string card string card@2x string list string list@2x string slimcover string slimcover@2x string
Rank status
The possible values are denoted either as integer or string.
Integer String -2 graveyard -1 wip 0 pending 1 ranked 2 approved 3 qualified 4 loved
BeatmapsetDiscussion
Represents a Beatmapset modding discussion.
Field Type Description beatmap BeatmapCompact? beatmap_id number? beatmapset BeatmapsetCompact? beatmapset_id number can_be_resolved boolean can_grant_kudosu boolean created_at Timestamp current_user_attributes CurrentUserAttributes deleted_at Timestamp? deleted_by_id number? id number kudosu_denied boolean last_post_at Timestamp message_type MessageType parent_id number? posts BeatmapsetDiscussionPost[]? resolved boolean starting_post BeatmapsetDiscussionPost? timestamp number? updated_at Timestamp user_id number
MessageType
Name Description hype mapper_note praise problem review suggestion
BeatmapsetDiscussionPost
Field Type Description beatmapset_discussion_id number created_at Timestamp deleted_at Timestamp? deleted_by_id number? id number last_editor_id number? message string system boolean updated_at Timestamp user_id number
BeatmapsetDiscussionVote
Field Type Description beatmapset_discussion_id number created_at Timestamp id number score number updated_at Timestamp user_id number
Build
Field Type created_at Timestamp display_version string id number update_stream UpdateStream? users number version string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes changelog_entries ChangelogEntry[] If the build has no changelog entries, a placeholder is generated. versions Versions
Versions
ChangelogEntry
Field Type category string created_at Timestamp? github_pull_request_id number? github_url string? id number? major boolean repository string? title string? type string url string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes github_user GithubUser If the changelog entry has no GitHub user, a placeholder is generated. message string? Entry message in Markdown format. Embedded HTML is allowed. message_html string? Entry message in HTML format.
ChatChannel
Represents an individual chat «channel» in the game.
Channel Types
Type Permission Check for Joining/Messaging PUBLIC PRIVATE is player in the allowed groups? (channel.allowed_groups) MULTIPLAYER is player currently in the mp game? SPECTATOR TEMPORARY deprecated PM see below (user_channels) GROUP is player in channel? (user_channels)
For PMs, two factors are taken into account:
ChatMessage
Represents an individual Message within a ChatChannel.
Field Type Description message_id number unique identifier for message sender_id number user_id of the sender channel_id number channel_id of where the message was sent timestamp string when the message was sent, ISO-8601 content string message content is_action boolean was this an action? i.e. /me dances sender UserCompact embedded UserCompact object to save additional api lookups
Comment
Represents an single comment.
Field Type Description commentable_id number ID of the object the comment is attached to commentable_type string type of object the comment is attached to created_at string ISO 8601 date deleted_at string? ISO 8601 date if the comment was deleted; null, otherwise edited_at string? ISO 8601 date if the comment was edited; null, otherwise edited_by_id number? user id of the user that edited the post; null, otherwise id number the ID of the comment legacy_name string? username displayed on legacy comments message string? markdown of the comment’s content message_html string? html version of the comment’s content parent_id number? ID of the comment’s parent pinned boolean Pin status of the comment replies_count number number of replies to the comment updated_at string ISO 8601 date user_id number user ID of the poster votes_count number number of votes
CommentBundle
Comments and related data.
Field Type Description commentable_meta CommentableMeta[] ID of the object the comment is attached to comments Comment[] Array of comments ordered according to sort ; cursor Cursor has_more boolean If there are more comments or replies available has_more_id number? included_comments Comment[] Related comments; e.g. parent comments and nested replies pinned_comments Comment[]? Pinned comments sort string one of the CommentSort types top_level_count number? Number of comments at the top level. Not returned for replies. total number? Total number of comments. Not retuned for replies. user_follow boolean is the current user watching the comment thread? user_votes number[] IDs of the comments in the bundle the current user has upvoted users UserCompact[] array of users related to the comments
CommentSort
Type Sort Fields new created_at (descending), id (descending) old created_at (ascending), id (ascending) top votes_count (descending), created_at (descending), id (descending)
Building cursor for comments listing
The returned response will be for comments after the specified sort fields.
For example, use last loaded comment for the fields value to load more comments. Also make sure to use same sort and parent_id values.
CommentableMeta
Metadata of the object that a comment is attached to.
Field Type Description id number the ID of the object title string display title type string the type of the object url string url of the object
CurrentUserAttributes
An object listing various related permissions and states for the current user, related to the object it is attached to.
BeatmapsetDiscussionPermissions
TODO: needs a better name.
Name Description can_destroy Can delete the discussion. can_reopen Can reopen the discussion. can_moderate_kudosu Can allow or deny kudosu. can_resolve Can resolve the discussion. vote_score Current vote given to the discussion.
ChatChannelUserAttributes
Name Type Description can_message boolean Can send messages to this channel. can_message_error string? Reason messages cannot be sent to this channel last_read_id number message_id of last message read.
Cursor
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.
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
osu!api open beta
Нет аккаунта?
osu!api open beta
I’ve had an API available for a while but until now it has been on a private on-request basis. In order to try and make developing third party services which expand and support osu!, I have added an API key setup and started to document the API.
Documentation will be expanded as I find time to do so! If anyone currently using the API is able to help expand the documentation then please do.
comentarinformal wrote:
Before I spam it with requests that might not exist, is there anything to get user’s information?
(Also, is there anything to login users from this page in other places?)
There is /api/get_user
Gonna write an entry with the information I have about it.
Is there a fair use limit? (e.g. no more than XX requests per day)
For get_user, I suppose there is a mode parameter for getting user information for Taiko, CtB and osu!mania? Or do I have to file an issue in GitHub? Nevermind, I found it, the parameter to add is called «m» I have edited the GitHub wiki.
Oh well. I have some questions:
Are only the beatmap and user endpoints available?
The parameter «since» in /get_beatmap how I need to pass the time on it? UTC or unix timestamp?
Do I need to pass the key on the wiki’s API too?
Edit: What the countX values mean? Number of beatmaps?
comentarinformal wrote:
Before I spam it with requests that might not exist, is there anything to get user’s information?
(Also, is there anything to login users from this page in other places?)
I guess I’ll update my userbar too when I find some time.
Damnae wrote:
I guess I’ll update my userbar too when I find some time.
I registered it for osu!userbar, but I also use it for my «Big ugly white signature», they are not on the same webserver, but it works fine
I belive only you and peppy can see the name you used, too.
(Yes I took my lazyness off, it was not that long to update ^^)
@Repflez: I tried using your API-powered signature and I get something weird.
Since I only aim for SS, I have 100% Accuracy all the time, and the Accuracy display is weird.
(I now know that despite having all-SS records, the note hit count for getting 50s and 100s are still counted all the time )
Winshley wrote:
@Repflez: I tried using your API-powered signature and I get something weird.
Since I only aim for SS, I have 100% Accuracy all the time, and the Accuracy display is weird.
(I now know that despite having all-SS records, the note hit count for getting 50s and 100s are still counted all the time )
So that’s what the CountX values mean. Thanks for that. I already went and changed the accuracy to show a centered «100% Accuracy» if it’s 100. Forget that. I ditched the bar on it and used the extra space for showing the PP.
(I love how the 300 count ended overlaping the border)
Repflez wrote:
So that’s what the CountX values mean. Thanks for that.
Yeah. At first I thought that there was something wrong with the API showing 50s and 100s despite having 100% Accuracy, until I actually calculated all 300s + 100s + 50s = «Total Hits» on our profile.
About the 300 overlap though, it does need some fix:
When you reached 10 millions of 300 hits, the last number is cut off. Cookiezi has 17 millions of 300 hits.
I’m not sure how the level bar breaking happens though. I was thinking that it probably because I don’t have any ranked score on osu!mania?
[Archived] getting osu! api token
Нет аккаунта?
[Archived] getting osu! api token
here is the website I am currently using this for https://osu-api-crap.minecreeper0913.repl.co
well since the project I am using is all python and not javascript I am using a new tab browser to just test it and so far the code I am using is
url = («https://osu.ppy.sh/oauth/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=%s» % (code))
the &code=%s is basically just grabbing the code that has been given back by oauth and using that as the url, when I am testing it though I am actually using my code
Never share your client secret, it’s secret for a reason. I would recommend resetting it ASAP.
Are you just typing that URL into your browser or are you actually sending it as a post request with whatever python code you have? Typing the URL into your browser won’t work.
The token endpoint takes the parameters in the body of the request, not as query parameters. You are also missing some parameters, like redirect_uri and grant_type.
If you are using python’s requests library, you can do something like this:
Might have some syntax errors because I wrote that from memory and didn’t check anything in an IDE or by running it.
You can try without specifying the content type in your headers, it might work without it. Very simply, the content type header describes what type of content or data is being sent. As far as I recall, the server is expecting that content type but I could be wrong.
now starting to realize that I might have done this a bit wrong, this is the first time I have used an API for something so everything I am doing is new to me.
So the first thing that is happening is that you press the login to link your osu API to the website, then it grabs your code and redirects you to the home website with the code in the url for example http://www.website.com/code=j9838r9y82g9438gh8243hg384hg, and it is supposed to use that, but when in testing it just returns favicon.ico, and I don’t know what that is or means so I might have to change my get request, another issue is but how would I make it get that auth code?
I don’t know anything about the project you are working on, so unfortunately I don’t think I can really answer any of the questions you’re asking.
I don’t know what you mean by a favicon being returned and I also don’t know what you are using the handle the backend of your site, so I can’t specifically tell you how to grab the code. Whatever you are using should have some way of getting query parameters from the URL.
Oauth2 is a very standardized and should be nearly the same everywhere that uses it. osu! is no exception. I would highly recommend looking up and reading about the authorization code flow that you are trying to use here. There should be a ton of resources and maybe a few code examples as well.
There might not be any videos specific to osu!’s API, but there are definitely Oauth2 tutorial videos and examples out there in probably every programming language, which is what you are dealing with right now.
For example, here is a video I found after a quick Google search that is using Python. I can’t fully comment on its quality since I just skimmed through it, but the general flow that the creator of the video goes over seems like it will at least cover how OAuth2 works in general, even if it’s not in the context of osu!’s API.
And even if you don’t really like reading, there are still some pretty good resources you can use that might help in addition to watching a video. Like this and this for example. Again, I’ve only skimmed through these, but they also seem to be pretty good.
here is the code I use:
NOTE I did not actually use SECRET as the secret I have it as SECRET because its secret
/reports
/rooms
/rooms//seasonal-backgrounds
/scores///download
/scores///beatmapsets/search//beatmapsets/lookup
/beatmapsets//friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
Similar to Get User but with authenticated user (token owner) as user id.
Response format
Additionally, statistics_rulesets is included, containing statistics for all rulesets.
Get User Kudosu
Returns kudosu history.
Response format
Get User Scores
This endpoint returns the scores of specified user.
Response format
Array of Score. Following attributes are included in the response object when applicable.
Get User Beatmaps
Returns the beatmaps of specified user.
Type Notes favourite graveyard loved most_played pending Previously unranked ranked Previously ranked_and_approved
Response format
Array of BeatmapPlaycount when type is most_played ; array of Beatmapset, otherwise.
Get User Recent Activity
Returns recent activity.
Response format
Get User
This endpoint returns the detail of specified user.
Response format
Returns User object. The following optional attributes on UserCompact are included:
Get Users
Returns list of users.
Response format
Field Type Description users UserCompact[] Includes: country, cover, groups, statistics_rulesets.
Get Wiki Page
The wiki article or image data.
Response Format
Notification Websocket
Connection
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:
Field Type Description event string See below
logout event
Server will disconnect session after sending this event so don’t try to reconnect.
Field Type Description event string logout
new event
New notification. See Notification object for notification types.
Field Type Description event string new data Notification
read event
Notification has been read.
Field Type Description event string read ids number[] id of Notifications which are read
Object Structures
Beatmap
Represent a beatmap. This extends BeatmapCompact with additional attributes.
Field Type Description accuracy float ar float beatmapset_id integer bpm float? convert boolean count_circles integer count_sliders integer count_spinners integer cs float deleted_at Timestamp? drain float hit_length integer is_scoreable boolean last_updated Timestamp mode_int integer passcount integer playcount integer ranked integer See Rank status for list of possible values. url string
BeatmapCompact
Represent a beatmap.
Field Type Description beatmapset_id integer difficulty_rating float id integer mode GameMode status string See Rank status for list of possible values. total_length integer user_id integer version string
Field Type Description beatmapset Beatmapset|BeatmapsetCompact|null Beatmapset for Beatmap object, BeatmapsetCompact for BeatmapCompact object. null if the beatmap doesn’t have associated beatmapset (e.g. deleted). checksum string? failtimes Failtimes max_combo integer
Failtimes
All fields are optional but there’s always at least one field returned.
Field Type Description exit integer[]? Array of length 100. fail integer[]? Array of length 100.
BeatmapDifficultyAttributes
Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.
Field Type max_combo integer star_rating float
Field Type aim_difficulty float approach_rate float flashlight_difficulty float overall_difficulty float slider_factor float speed_difficulty float
taiko
Field Type stamina_difficulty float rhythm_difficulty float colour_difficulty float approach_rate float great_hit_window float
fruits
mania
Field Type great_hit_window float score_multiplier float
BeatmapPlaycount
Represent the playcount of a beatmap.
Field Type Description beatmap_id number beatmap BeatmapCompact? beatmapset BeatmapsetCompact? count number
BeatmapScores
Field Type Description scores Score[] The list of top scores for the beatmap in descending order. userScore BeatmapUserScore? The score of the current user. This is not returned if the current user does not have a score. Note: will be moved to user_score in the future
BeatmapUserScore
Field Type Description position number The position of the score within the requested beatmap ranking. score Score The details of the score.
Beatmapset
Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.
Field Type Description availability.download_disabled boolean availability.more_information string? bpm float can_be_hyped boolean creator string Username of the mapper at the time of beatmapset creation. discussion_locked boolean hype.current integer hype.required integer is_scoreable boolean last_updated Timestamp legacy_thread_url string? nominations.current integer nominations.required integer ranked integer See Rank status for list of possible values. ranked_date Timestamp? source string storyboard boolean submitted_date Timestamp? tags string
The following attributes are always included as well:
Field has_favourited
BeatmapsetCompact
Represents a beatmapset.
Field Type Description artist string artist_unicode string covers Covers creator string favourite_count number id number nsfw boolean play_count number preview_url string source string status string title string title_unicode string user_id number video boolean
Those fields are optional.
Field Type Description beatmaps Beatmap[] converts current_user_attributes description discussions events genre has_favourited boolean language nominations ratings recent_favourites related_users user
Covers
Field Type cover string cover@2x string card string card@2x string list string list@2x string slimcover string slimcover@2x string
Rank status
The possible values are denoted either as integer or string.
Integer String -2 graveyard -1 wip 0 pending 1 ranked 2 approved 3 qualified 4 loved
BeatmapsetDiscussion
Represents a Beatmapset modding discussion.
Field Type Description beatmap BeatmapCompact? beatmap_id number? beatmapset BeatmapsetCompact? beatmapset_id number can_be_resolved boolean can_grant_kudosu boolean created_at Timestamp current_user_attributes CurrentUserAttributes deleted_at Timestamp? deleted_by_id number? id number kudosu_denied boolean last_post_at Timestamp message_type MessageType parent_id number? posts BeatmapsetDiscussionPost[]? resolved boolean starting_post BeatmapsetDiscussionPost? timestamp number? updated_at Timestamp user_id number
MessageType
Name Description hype mapper_note praise problem review suggestion
BeatmapsetDiscussionPost
Field Type Description beatmapset_discussion_id number created_at Timestamp deleted_at Timestamp? deleted_by_id number? id number last_editor_id number? message string system boolean updated_at Timestamp user_id number
BeatmapsetDiscussionVote
Field Type Description beatmapset_discussion_id number created_at Timestamp id number score number updated_at Timestamp user_id number
Build
Field Type created_at Timestamp display_version string id number update_stream UpdateStream? users number version string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes changelog_entries ChangelogEntry[] If the build has no changelog entries, a placeholder is generated. versions Versions
Versions
ChangelogEntry
Field Type category string created_at Timestamp? github_pull_request_id number? github_url string? id number? major boolean repository string? title string? type string url string?
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
Field Type Notes github_user GithubUser If the changelog entry has no GitHub user, a placeholder is generated. message string? Entry message in Markdown format. Embedded HTML is allowed. message_html string? Entry message in HTML format.
ChatChannel
Represents an individual chat «channel» in the game.
Channel Types
Type Permission Check for Joining/Messaging PUBLIC PRIVATE is player in the allowed groups? (channel.allowed_groups) MULTIPLAYER is player currently in the mp game? SPECTATOR TEMPORARY deprecated PM see below (user_channels) GROUP is player in channel? (user_channels)
For PMs, two factors are taken into account:
ChatMessage
Represents an individual Message within a ChatChannel.
Field Type Description message_id number unique identifier for message sender_id number user_id of the sender channel_id number channel_id of where the message was sent timestamp string when the message was sent, ISO-8601 content string message content is_action boolean was this an action? i.e. /me dances sender UserCompact embedded UserCompact object to save additional api lookups
Comment
Represents an single comment.
Field Type Description commentable_id number ID of the object the comment is attached to commentable_type string type of object the comment is attached to created_at string ISO 8601 date deleted_at string? ISO 8601 date if the comment was deleted; null, otherwise edited_at string? ISO 8601 date if the comment was edited; null, otherwise edited_by_id number? user id of the user that edited the post; null, otherwise id number the ID of the comment legacy_name string? username displayed on legacy comments message string? markdown of the comment’s content message_html string? html version of the comment’s content parent_id number? ID of the comment’s parent pinned boolean Pin status of the comment replies_count number number of replies to the comment updated_at string ISO 8601 date user_id number user ID of the poster votes_count number number of votes
CommentBundle
Comments and related data.
Field Type Description commentable_meta CommentableMeta[] ID of the object the comment is attached to comments Comment[] Array of comments ordered according to sort ; cursor Cursor has_more boolean If there are more comments or replies available has_more_id number? included_comments Comment[] Related comments; e.g. parent comments and nested replies pinned_comments Comment[]? Pinned comments sort string one of the CommentSort types top_level_count number? Number of comments at the top level. Not returned for replies. total number? Total number of comments. Not retuned for replies. user_follow boolean is the current user watching the comment thread? user_votes number[] IDs of the comments in the bundle the current user has upvoted users UserCompact[] array of users related to the comments
CommentSort
Type Sort Fields new created_at (descending), id (descending) old created_at (ascending), id (ascending) top votes_count (descending), created_at (descending), id (descending)
Building cursor for comments listing
The returned response will be for comments after the specified sort fields.
For example, use last loaded comment for the fields value to load more comments. Also make sure to use same sort and parent_id values.
CommentableMeta
Metadata of the object that a comment is attached to.
Field Type Description id number the ID of the object title string display title type string the type of the object url string url of the object
CurrentUserAttributes
An object listing various related permissions and states for the current user, related to the object it is attached to.
BeatmapsetDiscussionPermissions
TODO: needs a better name.
Name Description can_destroy Can delete the discussion. can_reopen Can reopen the discussion. can_moderate_kudosu Can allow or deny kudosu. can_resolve Can resolve the discussion. vote_score Current vote given to the discussion.
ChatChannelUserAttributes
Name Type Description can_message boolean Can send messages to this channel. can_message_error string? Reason messages cannot be sent to this channel last_read_id number message_id of last message read.
Cursor
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.
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
osu!api open beta
Нет аккаунта?
osu!api open beta
I’ve had an API available for a while but until now it has been on a private on-request basis. In order to try and make developing third party services which expand and support osu!, I have added an API key setup and started to document the API.
Documentation will be expanded as I find time to do so! If anyone currently using the API is able to help expand the documentation then please do.
comentarinformal wrote:
Before I spam it with requests that might not exist, is there anything to get user’s information?
(Also, is there anything to login users from this page in other places?)
There is /api/get_user
Gonna write an entry with the information I have about it.
Is there a fair use limit? (e.g. no more than XX requests per day)
For get_user, I suppose there is a mode parameter for getting user information for Taiko, CtB and osu!mania? Or do I have to file an issue in GitHub? Nevermind, I found it, the parameter to add is called «m» I have edited the GitHub wiki.
Oh well. I have some questions:
Are only the beatmap and user endpoints available?
The parameter «since» in /get_beatmap how I need to pass the time on it? UTC or unix timestamp?
Do I need to pass the key on the wiki’s API too?
Edit: What the countX values mean? Number of beatmaps?
comentarinformal wrote:
Before I spam it with requests that might not exist, is there anything to get user’s information?
(Also, is there anything to login users from this page in other places?)
I guess I’ll update my userbar too when I find some time.
Damnae wrote:
I guess I’ll update my userbar too when I find some time.
I registered it for osu!userbar, but I also use it for my «Big ugly white signature», they are not on the same webserver, but it works fine
I belive only you and peppy can see the name you used, too.
(Yes I took my lazyness off, it was not that long to update ^^)
@Repflez: I tried using your API-powered signature and I get something weird.
Since I only aim for SS, I have 100% Accuracy all the time, and the Accuracy display is weird.
(I now know that despite having all-SS records, the note hit count for getting 50s and 100s are still counted all the time )
Winshley wrote:
@Repflez: I tried using your API-powered signature and I get something weird.
Since I only aim for SS, I have 100% Accuracy all the time, and the Accuracy display is weird.
(I now know that despite having all-SS records, the note hit count for getting 50s and 100s are still counted all the time )
So that’s what the CountX values mean. Thanks for that. I already went and changed the accuracy to show a centered «100% Accuracy» if it’s 100. Forget that. I ditched the bar on it and used the extra space for showing the PP.
(I love how the 300 count ended overlaping the border)
Repflez wrote:
So that’s what the CountX values mean. Thanks for that.
Yeah. At first I thought that there was something wrong with the API showing 50s and 100s despite having 100% Accuracy, until I actually calculated all 300s + 100s + 50s = «Total Hits» on our profile.
About the 300 overlap though, it does need some fix:
When you reached 10 millions of 300 hits, the last number is cut off. Cookiezi has 17 millions of 300 hits.
I’m not sure how the level bar breaking happens though. I was thinking that it probably because I don’t have any ranked score on osu!mania?
[Archived] getting osu! api token
Нет аккаунта?
[Archived] getting osu! api token
here is the website I am currently using this for https://osu-api-crap.minecreeper0913.repl.co
well since the project I am using is all python and not javascript I am using a new tab browser to just test it and so far the code I am using is
url = («https://osu.ppy.sh/oauth/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=%s» % (code))
the &code=%s is basically just grabbing the code that has been given back by oauth and using that as the url, when I am testing it though I am actually using my code
Never share your client secret, it’s secret for a reason. I would recommend resetting it ASAP.
Are you just typing that URL into your browser or are you actually sending it as a post request with whatever python code you have? Typing the URL into your browser won’t work.
The token endpoint takes the parameters in the body of the request, not as query parameters. You are also missing some parameters, like redirect_uri and grant_type.
If you are using python’s requests library, you can do something like this:
Might have some syntax errors because I wrote that from memory and didn’t check anything in an IDE or by running it.
You can try without specifying the content type in your headers, it might work without it. Very simply, the content type header describes what type of content or data is being sent. As far as I recall, the server is expecting that content type but I could be wrong.
now starting to realize that I might have done this a bit wrong, this is the first time I have used an API for something so everything I am doing is new to me.
So the first thing that is happening is that you press the login to link your osu API to the website, then it grabs your code and redirects you to the home website with the code in the url for example http://www.website.com/code=j9838r9y82g9438gh8243hg384hg, and it is supposed to use that, but when in testing it just returns favicon.ico, and I don’t know what that is or means so I might have to change my get request, another issue is but how would I make it get that auth code?
I don’t know anything about the project you are working on, so unfortunately I don’t think I can really answer any of the questions you’re asking.
I don’t know what you mean by a favicon being returned and I also don’t know what you are using the handle the backend of your site, so I can’t specifically tell you how to grab the code. Whatever you are using should have some way of getting query parameters from the URL.
Oauth2 is a very standardized and should be nearly the same everywhere that uses it. osu! is no exception. I would highly recommend looking up and reading about the authorization code flow that you are trying to use here. There should be a ton of resources and maybe a few code examples as well.
There might not be any videos specific to osu!’s API, but there are definitely Oauth2 tutorial videos and examples out there in probably every programming language, which is what you are dealing with right now.
For example, here is a video I found after a quick Google search that is using Python. I can’t fully comment on its quality since I just skimmed through it, but the general flow that the creator of the video goes over seems like it will at least cover how OAuth2 works in general, even if it’s not in the context of osu!’s API.
And even if you don’t really like reading, there are still some pretty good resources you can use that might help in addition to watching a video. Like this and this for example. Again, I’ve only skimmed through these, but they also seem to be pretty good.
here is the code I use:
NOTE I did not actually use SECRET as the secret I have it as SECRET because its secret
/beatmapsets/search//beatmapsets/lookup
/beatmapsets//friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
/friends
/me/download-quota-check
/beatmapsets//download
Users
Get Own Data
Similar to Get User but with authenticated user (token owner) as user id.
Response format
Additionally, statistics_rulesets is included, containing statistics for all rulesets.
Get User Kudosu
Returns kudosu history.
Response format
Get User Scores
This endpoint returns the scores of specified user.
Response format
Array of Score. Following attributes are included in the response object when applicable.
Get User Beatmaps
Returns the beatmaps of specified user.
| Type | Notes |
|---|---|
| favourite | |
| graveyard | |
| loved | |
| most_played | |
| pending | Previously unranked |
| ranked | Previously ranked_and_approved |
Response format
Array of BeatmapPlaycount when type is most_played ; array of Beatmapset, otherwise.
Get User Recent Activity
Returns recent activity.
Response format
Get User
This endpoint returns the detail of specified user.
Response format
Returns User object. The following optional attributes on UserCompact are included:
Get Users
Returns list of users.
Response format
| Field | Type | Description |
|---|---|---|
| users | UserCompact[] | Includes: country, cover, groups, statistics_rulesets. |
Get Wiki Page
The wiki article or image data.
Response Format
Notification Websocket
Connection
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:
| Field | Type | Description |
|---|---|---|
| event | string | See below |
logout event
Server will disconnect session after sending this event so don’t try to reconnect.
| Field | Type | Description |
|---|---|---|
| event | string | logout |
new event
New notification. See Notification object for notification types.
| Field | Type | Description |
|---|---|---|
| event | string | new |
| data | Notification |
read event
Notification has been read.
| Field | Type | Description |
|---|---|---|
| event | string | read |
| ids | number[] | id of Notifications which are read |
Object Structures
Beatmap
Represent a beatmap. This extends BeatmapCompact with additional attributes.
| Field | Type | Description |
|---|---|---|
| accuracy | float | |
| ar | float | |
| beatmapset_id | integer | |
| bpm | float? | |
| convert | boolean | |
| count_circles | integer | |
| count_sliders | integer | |
| count_spinners | integer | |
| cs | float | |
| deleted_at | Timestamp? | |
| drain | float | |
| hit_length | integer | |
| is_scoreable | boolean | |
| last_updated | Timestamp | |
| mode_int | integer | |
| passcount | integer | |
| playcount | integer | |
| ranked | integer | See Rank status for list of possible values. |
| url | string |
BeatmapCompact
Represent a beatmap.
| Field | Type | Description |
|---|---|---|
| beatmapset_id | integer | |
| difficulty_rating | float | |
| id | integer | |
| mode | GameMode | |
| status | string | See Rank status for list of possible values. |
| total_length | integer | |
| user_id | integer | |
| version | string |
| Field | Type | Description |
|---|---|---|
| beatmapset | Beatmapset|BeatmapsetCompact|null | Beatmapset for Beatmap object, BeatmapsetCompact for BeatmapCompact object. null if the beatmap doesn’t have associated beatmapset (e.g. deleted). |
| checksum | string? | |
| failtimes | Failtimes | |
| max_combo | integer |
Failtimes
All fields are optional but there’s always at least one field returned.
| Field | Type | Description |
|---|---|---|
| exit | integer[]? | Array of length 100. |
| fail | integer[]? | Array of length 100. |
BeatmapDifficultyAttributes
Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.
| Field | Type |
|---|---|
| max_combo | integer |
| star_rating | float |
| Field | Type |
|---|---|
| aim_difficulty | float |
| approach_rate | float |
| flashlight_difficulty | float |
| overall_difficulty | float |
| slider_factor | float |
| speed_difficulty | float |
taiko
| Field | Type |
|---|---|
| stamina_difficulty | float |
| rhythm_difficulty | float |
| colour_difficulty | float |
| approach_rate | float |
| great_hit_window | float |
fruits
mania
| Field | Type |
|---|---|
| great_hit_window | float |
| score_multiplier | float |
BeatmapPlaycount
Represent the playcount of a beatmap.
| Field | Type | Description |
|---|---|---|
| beatmap_id | number | |
| beatmap | BeatmapCompact? | |
| beatmapset | BeatmapsetCompact? | |
| count | number |
BeatmapScores
| Field | Type | Description |
|---|---|---|
| scores | Score[] | The list of top scores for the beatmap in descending order. |
| userScore | BeatmapUserScore? | The score of the current user. This is not returned if the current user does not have a score. Note: will be moved to user_score in the future |
BeatmapUserScore
| Field | Type | Description |
|---|---|---|
| position | number | The position of the score within the requested beatmap ranking. |
| score | Score | The details of the score. |
Beatmapset
Represents a beatmapset. This extends BeatmapsetCompact with additional attributes.
| Field | Type | Description |
|---|---|---|
| availability.download_disabled | boolean | |
| availability.more_information | string? | |
| bpm | float | |
| can_be_hyped | boolean | |
| creator | string | Username of the mapper at the time of beatmapset creation. |
| discussion_locked | boolean | |
| hype.current | integer | |
| hype.required | integer | |
| is_scoreable | boolean | |
| last_updated | Timestamp | |
| legacy_thread_url | string? | |
| nominations.current | integer | |
| nominations.required | integer | |
| ranked | integer | See Rank status for list of possible values. |
| ranked_date | Timestamp? | |
| source | string | |
| storyboard | boolean | |
| submitted_date | Timestamp? | |
| tags | string |
The following attributes are always included as well:
| Field |
|---|
| has_favourited |
BeatmapsetCompact
Represents a beatmapset.
| Field | Type | Description |
|---|---|---|
| artist | string | |
| artist_unicode | string | |
| covers | Covers | |
| creator | string | |
| favourite_count | number | |
| id | number | |
| nsfw | boolean | |
| play_count | number | |
| preview_url | string | |
| source | string | |
| status | string | |
| title | string | |
| title_unicode | string | |
| user_id | number | |
| video | boolean |
Those fields are optional.
| Field | Type | Description |
|---|---|---|
| beatmaps | Beatmap[] | |
| converts | ||
| current_user_attributes | ||
| description | ||
| discussions | ||
| events | ||
| genre | ||
| has_favourited | boolean | |
| language | ||
| nominations | ||
| ratings | ||
| recent_favourites | ||
| related_users | ||
| user |
Covers
| Field | Type |
|---|---|
| cover | string |
| cover@2x | string |
| card | string |
| card@2x | string |
| list | string |
| list@2x | string |
| slimcover | string |
| slimcover@2x | string |
Rank status
The possible values are denoted either as integer or string.
| Integer | String |
|---|---|
| -2 | graveyard |
| -1 | wip |
| 0 | pending |
| 1 | ranked |
| 2 | approved |
| 3 | qualified |
| 4 | loved |
BeatmapsetDiscussion
Represents a Beatmapset modding discussion.
| Field | Type | Description |
|---|---|---|
| beatmap | BeatmapCompact? | |
| beatmap_id | number? | |
| beatmapset | BeatmapsetCompact? | |
| beatmapset_id | number | |
| can_be_resolved | boolean | |
| can_grant_kudosu | boolean | |
| created_at | Timestamp | |
| current_user_attributes | CurrentUserAttributes | |
| deleted_at | Timestamp? | |
| deleted_by_id | number? | |
| id | number | |
| kudosu_denied | boolean | |
| last_post_at | Timestamp | |
| message_type | MessageType | |
| parent_id | number? | |
| posts | BeatmapsetDiscussionPost[]? | |
| resolved | boolean | |
| starting_post | BeatmapsetDiscussionPost? | |
| timestamp | number? | |
| updated_at | Timestamp | |
| user_id | number |
MessageType
| Name | Description |
|---|---|
| hype | |
| mapper_note | |
| praise | |
| problem | |
| review | |
| suggestion |
BeatmapsetDiscussionPost
| Field | Type | Description |
|---|---|---|
| beatmapset_discussion_id | number | |
| created_at | Timestamp | |
| deleted_at | Timestamp? | |
| deleted_by_id | number? | |
| id | number | |
| last_editor_id | number? | |
| message | string | |
| system | boolean | |
| updated_at | Timestamp | |
| user_id | number |
BeatmapsetDiscussionVote
| Field | Type | Description |
|---|---|---|
| beatmapset_discussion_id | number | |
| created_at | Timestamp | |
| id | number | |
| score | number | |
| updated_at | Timestamp | |
| user_id | number |
Build
| Field | Type |
|---|---|
| created_at | Timestamp |
| display_version | string |
| id | number |
| update_stream | UpdateStream? |
| users | number |
| version | string? |
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
| Field | Type | Notes |
|---|---|---|
| changelog_entries | ChangelogEntry[] | If the build has no changelog entries, a placeholder is generated. |
| versions | Versions |
Versions
ChangelogEntry
| Field | Type |
|---|---|
| category | string |
| created_at | Timestamp? |
| github_pull_request_id | number? |
| github_url | string? |
| id | number? |
| major | boolean |
| repository | string? |
| title | string? |
| type | string |
| url | string? |
Optional Attributes
The following are attributes which may be additionally included in responses. Relevant endpoints should list them if applicable.
| Field | Type | Notes |
|---|---|---|
| github_user | GithubUser | If the changelog entry has no GitHub user, a placeholder is generated. |
| message | string? | Entry message in Markdown format. Embedded HTML is allowed. |
| message_html | string? | Entry message in HTML format. |
ChatChannel
Represents an individual chat «channel» in the game.
Channel Types
| Type | Permission Check for Joining/Messaging |
|---|---|
| PUBLIC | |
| PRIVATE | is player in the allowed groups? (channel.allowed_groups) |
| MULTIPLAYER | is player currently in the mp game? |
| SPECTATOR | |
| TEMPORARY | deprecated |
| PM | see below (user_channels) |
| GROUP | is player in channel? (user_channels) |
For PMs, two factors are taken into account:
ChatMessage
Represents an individual Message within a ChatChannel.
| Field | Type | Description |
|---|---|---|
| message_id | number | unique identifier for message |
| sender_id | number | user_id of the sender |
| channel_id | number | channel_id of where the message was sent |
| timestamp | string | when the message was sent, ISO-8601 |
| content | string | message content |
| is_action | boolean | was this an action? i.e. /me dances |
| sender | UserCompact | embedded UserCompact object to save additional api lookups |
Comment
Represents an single comment.
| Field | Type | Description |
|---|---|---|
| commentable_id | number | ID of the object the comment is attached to |
| commentable_type | string | type of object the comment is attached to |
| created_at | string | ISO 8601 date |
| deleted_at | string? | ISO 8601 date if the comment was deleted; null, otherwise |
| edited_at | string? | ISO 8601 date if the comment was edited; null, otherwise |
| edited_by_id | number? | user id of the user that edited the post; null, otherwise |
| id | number | the ID of the comment |
| legacy_name | string? | username displayed on legacy comments |
| message | string? | markdown of the comment’s content |
| message_html | string? | html version of the comment’s content |
| parent_id | number? | ID of the comment’s parent |
| pinned | boolean | Pin status of the comment |
| replies_count | number | number of replies to the comment |
| updated_at | string | ISO 8601 date |
| user_id | number | user ID of the poster |
| votes_count | number | number of votes |
CommentBundle
Comments and related data.
| Field | Type | Description |
|---|---|---|
| commentable_meta | CommentableMeta[] | ID of the object the comment is attached to |
| comments | Comment[] | Array of comments ordered according to sort ; |
| cursor | Cursor | |
| has_more | boolean | If there are more comments or replies available |
| has_more_id | number? | |
| included_comments | Comment[] | Related comments; e.g. parent comments and nested replies |
| pinned_comments | Comment[]? | Pinned comments |
| sort | string | one of the CommentSort types |
| top_level_count | number? | Number of comments at the top level. Not returned for replies. |
| total | number? | Total number of comments. Not retuned for replies. |
| user_follow | boolean | is the current user watching the comment thread? |
| user_votes | number[] | IDs of the comments in the bundle the current user has upvoted |
| users | UserCompact[] | array of users related to the comments |
CommentSort
| Type | Sort Fields |
|---|---|
| new | created_at (descending), id (descending) |
| old | created_at (ascending), id (ascending) |
| top | votes_count (descending), created_at (descending), id (descending) |
Building cursor for comments listing
The returned response will be for comments after the specified sort fields.
For example, use last loaded comment for the fields value to load more comments. Also make sure to use same sort and parent_id values.
CommentableMeta
Metadata of the object that a comment is attached to.
| Field | Type | Description |
|---|---|---|
| id | number | the ID of the object |
| title | string | display title |
| type | string | the type of the object |
| url | string | url of the object |
CurrentUserAttributes
An object listing various related permissions and states for the current user, related to the object it is attached to.
BeatmapsetDiscussionPermissions
TODO: needs a better name.
| Name | Description |
|---|---|
| can_destroy | Can delete the discussion. |
| can_reopen | Can reopen the discussion. |
| can_moderate_kudosu | Can allow or deny kudosu. |
| can_resolve | Can resolve the discussion. |
| vote_score | Current vote given to the discussion. |
ChatChannelUserAttributes
| Name | Type | Description |
|---|---|---|
| can_message | boolean | Can send messages to this channel. |
| can_message_error | string? | Reason messages cannot be sent to this channel |
| last_read_id | number | message_id of last message read. |
Cursor
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.
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
osu!api open beta
Нет аккаунта?
osu!api open beta
I’ve had an API available for a while but until now it has been on a private on-request basis. In order to try and make developing third party services which expand and support osu!, I have added an API key setup and started to document the API.
Documentation will be expanded as I find time to do so! If anyone currently using the API is able to help expand the documentation then please do.
comentarinformal wrote:
Before I spam it with requests that might not exist, is there anything to get user’s information?
(Also, is there anything to login users from this page in other places?)
There is /api/get_user
Gonna write an entry with the information I have about it.
Is there a fair use limit? (e.g. no more than XX requests per day)
For get_user, I suppose there is a mode parameter for getting user information for Taiko, CtB and osu!mania? Or do I have to file an issue in GitHub? Nevermind, I found it, the parameter to add is called «m» 
I have edited the GitHub wiki.
Oh well. I have some questions:
Are only the beatmap and user endpoints available?
The parameter «since» in /get_beatmap how I need to pass the time on it? UTC or unix timestamp?
Do I need to pass the key on the wiki’s API too?
Edit: What the countX values mean? Number of beatmaps?
comentarinformal wrote:
Before I spam it with requests that might not exist, is there anything to get user’s information?
(Also, is there anything to login users from this page in other places?)
I guess I’ll update my userbar too when I find some time.
Damnae wrote:
I guess I’ll update my userbar too when I find some time.
I registered it for osu!userbar, but I also use it for my «Big ugly white signature», they are not on the same webserver, but it works fine 
I belive only you and peppy can see the name you used, too.
(Yes I took my lazyness off, it was not that long to update ^^)
@Repflez: I tried using your API-powered signature and I get something weird.
Since I only aim for SS, I have 100% Accuracy all the time, and the Accuracy display is weird.
(I now know that despite having all-SS records, the note hit count for getting 50s and 100s are still counted all the time 
)
Winshley wrote:
@Repflez: I tried using your API-powered signature and I get something weird.
Since I only aim for SS, I have 100% Accuracy all the time, and the Accuracy display is weird.
(I now know that despite having all-SS records, the note hit count for getting 50s and 100s are still counted all the time )
So that’s what the CountX values mean. Thanks for that. I already went and changed the accuracy to show a centered «100% Accuracy» if it’s 100. Forget that. I ditched the bar on it and used the extra space for showing the PP.
(I love how the 300 count ended overlaping the border)
Repflez wrote:
So that’s what the CountX values mean. Thanks for that.
Yeah. At first I thought that there was something wrong with the API showing 50s and 100s despite having 100% Accuracy, until I actually calculated all 300s + 100s + 50s = «Total Hits» on our profile.
About the 300 overlap though, it does need some fix:
When you reached 10 millions of 300 hits, the last number is cut off. Cookiezi has 17 millions of 300 hits.
I’m not sure how the level bar breaking happens though. I was thinking that it probably because I don’t have any ranked score on osu!mania? 
[Archived] getting osu! api token
Нет аккаунта?
[Archived] getting osu! api token
here is the website I am currently using this for https://osu-api-crap.minecreeper0913.repl.co
well since the project I am using is all python and not javascript I am using a new tab browser to just test it and so far the code I am using is
url = («https://osu.ppy.sh/oauth/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=%s» % (code))
the &code=%s is basically just grabbing the code that has been given back by oauth and using that as the url, when I am testing it though I am actually using my code
Never share your client secret, it’s secret for a reason. I would recommend resetting it ASAP.
Are you just typing that URL into your browser or are you actually sending it as a post request with whatever python code you have? Typing the URL into your browser won’t work.
The token endpoint takes the parameters in the body of the request, not as query parameters. You are also missing some parameters, like redirect_uri and grant_type.
If you are using python’s requests library, you can do something like this:
Might have some syntax errors because I wrote that from memory and didn’t check anything in an IDE or by running it.
You can try without specifying the content type in your headers, it might work without it. Very simply, the content type header describes what type of content or data is being sent. As far as I recall, the server is expecting that content type but I could be wrong.
now starting to realize that I might have done this a bit wrong, this is the first time I have used an API for something so everything I am doing is new to me.
So the first thing that is happening is that you press the login to link your osu API to the website, then it grabs your code and redirects you to the home website with the code in the url for example http://www.website.com/code=j9838r9y82g9438gh8243hg384hg, and it is supposed to use that, but when in testing it just returns favicon.ico, and I don’t know what that is or means so I might have to change my get request, another issue is but how would I make it get that auth code?
I don’t know anything about the project you are working on, so unfortunately I don’t think I can really answer any of the questions you’re asking.
I don’t know what you mean by a favicon being returned and I also don’t know what you are using the handle the backend of your site, so I can’t specifically tell you how to grab the code. Whatever you are using should have some way of getting query parameters from the URL.
Oauth2 is a very standardized and should be nearly the same everywhere that uses it. osu! is no exception. I would highly recommend looking up and reading about the authorization code flow that you are trying to use here. There should be a ton of resources and maybe a few code examples as well.
There might not be any videos specific to osu!’s API, but there are definitely Oauth2 tutorial videos and examples out there in probably every programming language, which is what you are dealing with right now.
For example, here is a video I found after a quick Google search that is using Python. I can’t fully comment on its quality since I just skimmed through it, but the general flow that the creator of the video goes over seems like it will at least cover how OAuth2 works in general, even if it’s not in the context of osu!’s API.
And even if you don’t really like reading, there are still some pretty good resources you can use that might help in addition to watching a video. Like this and this for example. Again, I’ve only skimmed through these, but they also seem to be pretty good.
here is the code I use:
NOTE I did not actually use SECRET as the secret I have it as SECRET because its secret