keii.dev
1{{--
2 Copyright (c) ppy Pty Ltd <contact@ppy.sh>. Licensed under the GNU Affero General Public License v3.0.
3 See the LICENCE file in the repository root for full licence text.
4--}}
5# Introduction
6
7Welcome to the documentation for osu!api v2. You can use this API to get information on various circles and those who click them.
8
9Note 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.
10
11If you notice any errors in the documentation or encounter problems using the API, please check for (or create if necessary) [issues on GitHub](https://github.com/ppy/osu-web/issues). Alternatively, you can ask in `#osu-web` [on the development discord](https://discord.gg/ppy).
12
13Code 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.
14
15# Terms of Use
16
17Use the API for good. Don't overdo it. If in doubt, ask before (ab)using :). _this section may expand as necessary_.
18
19Current 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](mailto:pe@ppy.sh) a yell.
20
21# Wrappers
22
23Below is a list of some language-specific wrappers maintained by the community. Your mileage may vary when using them – please report any issues to the wrapper first before reporting back to us.
24
25- [ossapi](https://github.com/tybug/ossapi) (python)
26- [aiosu](https://github.com/NiceAesth/aiosu) (python)
27- [osu.py](https://github.com/sheppsu/osu.py) (python)
28- [rosu-v2](https://github.com/MaxOhn/rosu-v2) (rust)
29- [osu.js](https://github.com/L-Mario564/osu.js) (javascript/typescript)
30- [osu-api-v2-js](https://github.com/TTTaevas/osu-api-v2-js) (javascript/typescript)
31
32# Changelog
33
34For a full list of changes, see the
35[Changelog on the site]({{ route('changelog.show', ['changelog' => 'web']) }}).
36
37## Breaking Changes
38
39### 2024-07-30
40- `key` parameter for Get User endpoint has been deprecated. Prefix username with `@` to lookup by username instead.
41
42### 2024-01-23
43- `active_tournament_banner` in [User](#user) has been deprecated, use `active_tournament_banners` instead.
44
45### 2023-10-17
46- GameMode has been renamed to [Ruleset](#ruleset); existing property names remain unchanged.
47- `number` has been removed from documentation and replaced with `integer` or `float` to better reflect the type of number.
48
49### 2023-09-11
50- object structures with two main variants (Beatmap, Beatmapset, and User) have their naming changed. The base object which previously has `Compact` suffix has their suffix removed and the previously extended object with no suffix now has `Extended` suffix instead. This matches existing TypeScript interface.
51
52### 2023-02-17
53- `content_html` in [ChatMessage](#chatmessage) has been deprecated; pre-rendered markdown will be removed.
54
55### 2023-01-05
56- `new_channel_id` in [Create New PM](#create-new-pm) response has been deprecated, use `channel.channel_id` instead.
57
58### 2022-11-21
59- `messages` has been removed from Chat [Get Updates](#get-updates).
60
61### 2022-11-11
62- `recent_messages` in [ChatChannel](#chatchannel) has been deprecated, it will be removed from [Create Channel](#create-channel) response in the near future.
63
64### 2022-09-27
65- `user` include in [Get User Scores](#get-user-scores) response has been deprecated, it will be removed in the near future.
66
67### 2022-07-06
68- `chat/presence` endpoint has been deprecated, it will be removed in the near future.
69
70### 2022-06-08
71- `discussion_enabled` in Beatmapset is deprecated. All beatmapsets now have it enabled.
72
73### 2021-10-28
74- `beatmap` in [Get Beatmap scores](#get-beatmap-scores) `scores` array item is removed (it's never been documented in the first place).
75
76### 2021-09-01
77- `last_read_id` in [ChatChannel](#chatchannel) is deprecated, use `current_user_attributes.last_read_id` instead.
78
79### 2021-08-11
80- `bot` scope removed in favour for `delegate` scope [Client Credentials Delegation](#client-credentials-delegation).
81
82### 2021-06-14
83- Removed `description` from [UserGroup](#usergroup). It has been moved to an optional attribute with a different type on [Group](#group).
84
85### 2021-06-09
86- `ranked_and_approved_beatmapset_count` and `unranked_beatmapset_count` attributes in UserCompact object have been deprecated and replaced with `ranked_beatmapset_count` and `pending_beatmapset_count` respectively.
87- `ranked_and_approved` and `unranked` types in [Get User Beatmaps](#get-user-beatmaps) have been deprecated and replaced with `ranked` and `pending` respectively.
88
89### 2021-04-20
90- `cover_url` in User is deprecated, use `cover.url` instead.
91
92### 2021-02-25
93- `current_mode_rank` has been removed from UserCompact
94- attributes in [UserStatistics](#userstatistics) have been moved around
95 - `rank.country` is deprecated, replaced by `country_rank`
96 - `rank.global` and `pp_rank` are removed, replaced by `global_rank`
97
98### 2020-09-08
99- `presence` removed from `chat/new` response.
100
101### 2020-08-28
102- `/rooms/{room_id}/leaderboard` no longer returns an array at the top level; an object with keys is now returned.
103
104### 2020-05-01
105- `users.read` scope removed, replaced with more general `public` scope.
106
107### 2020-02-18
108- Beatmap `max_combo` and build update stream `user_count` now return the values as primitives instead of numbers wrapped in an array.
109
110### 2019-10-09
111- Ranking API response no longer returns an array at the top level; an object with keys is now returned.
112
113### 2019-07-18
114- User now returns counts directly as primitives instead of numbers wrapped in an array.
115
116
117# Endpoint
118
119## Base URL
120
121The base URL is: `{{ $GLOBALS['cfg']['app']['url'] }}/api/[version]/`
122
123## API Versions
124
125This is combined with the base endpoint to determine where requests should be sent.
126
127Version | Status
128------- | ---------------------------------------------------------------
129v2 | current
130v1 | _legacy api provided by the old site, will be deprecated soon_
131
132### API Response Version
133
134Sometimes, an API response need to be updated in non-backward compatible ways. In such cases, the `x-api-version` header is used to determine which version of the response will be returned.
135
136Version 0 is assumed when the header is omitted.
137
138Version | Change
139-------- | ------
14020220705 | [Score](#score) object with different set of fields.
14120240529 | [`GET /rooms`](#get-multiplayer-rooms) will not return rooms with category `daily_challenge` prior to this version. Temporary, will not be supported after 2024-11-29.
142
143## Language
144
145Language for the response is determined by `Accept-Language` header when specified. Specifying `*` or not setting the header will set the language to user configured language when accessing API as a user.