Public API

Datenshi exposes a public read-only REST API at https://osu.datenshi.pw/api/v1. Everything on this page works with no API key or login — just send a GET request. Responses are JSON.

If you're building a tool, bot, or stats site against Datenshi, this is the surface to build against. Endpoints not listed here require authentication and aren't covered by this page.

Quick reference

Method	Path	Description
GET	/users	Look up one user, or batch-lookup a list of users
GET	/users/scores/best	A user's best plays
GET	/users/scores/recent	A user's most recent plays
GET	/users/scores/first	A user's first-place plays
GET	/scores	Scores set on a beatmap
GET	/users/achievements	A user's achievement list
GET	/users/most_played	A user's most-played beatmaps
GET	/users/history	Rank / playcount / replays-watched history
GET	/beatmaps	Single beatmap, or a list by set/MD5/IDs
GET	/leaderboard	Global pp leaderboard
GET	/leaderboard/score	Global ranked-score leaderboard
GET	/leaderboard/country	Country-aggregate leaderboard
GET	/clans	Single clan, or a list of all clans
GET	/clans/members	A clan's roster with stats
GET	/clans/stats/all	Ranked clan leaderboard
GET	/multi/matches	List of multiplayer matches
GET	/multi/match	Single match detail + games
GET	/multi/matches/players	Match ↔ player pairs
GET	/badges	List of all badges
GET	/badges/members	Users holding a given badge
GET	/topdonors	Top donors leaderboard
GET	/stats	Server-wide summary counters
GET	/staff	Current staff roster

Pagination

Endpoints that return a list use p (page, 1-indexed, default 1) and l (page size). There's no cursor pagination. Most endpoints don't cap l server-side — be a good citizen and don't ask for absurd page sizes. clans/stats/all and topdonors cap at 100; leaderboard/leaderboard/score/leaderboard/country cap at 500.

A total count is only included on leaderboard/country and clans/stats/all — everything else just returns the page's items with no total.

Users

GET /users

Returns a list when ids or has_privileges is present; otherwise falls back to a single-user lookup by id/name.

Param	Type	Description
id	int	Single-user lookup
name	string	Single-user lookup by username
ids	csv int	Batch lookup — switches to list mode
has_privileges	int64 bitmask	Filter by account role bitmask — also triggers list mode
p	int	Page number (default 1)
l	int	Page size (default 50)

GET /users?ids=2,3

{
  "code": 200,
  "users": [
    {
      "id": 2,
      "username": "Kobo Kanaeru",
      "username_aka": "troke",
      "registered_on": "2020-12-24T05:44:27Z",
      "latest_activity": "2026-07-17T04:48:08Z",
      "country": "ID",
      "score_reset_flag": false
    }
  ]
}

GET /users/scores/best / /users/scores/recent / /users/scores/first

Three sibling endpoints with an identical parameter shape — only the sort criteria differs.

Param	Type	Description
id / name	int / string	User resolver (one required)
mode	int	0=std, 1=taiko, 2=ctb, 3=mania (default 0)
smode	int	0=vanilla, 1=relax, 2=autopilot (default 0)
p	int	Page number (default 1)
l	int	Page size (default 50)

GET /users/scores/best?id=2&mode=0&l=5

{
  "code": 200,
  "scores": [
    {
      "id": 8834211,
      "beatmap_md5": "a3f9c2e1b7d84f0912ab34cd56ef7890",
      "score": 987654321,
      "max_combo": 1532,
      "full_combo": true,
      "mods": 88,
      "count_300": 1420, "count_100": 12, "count_50": 0,
      "count_geki": 0, "count_katu": 0, "count_miss": 0,
      "time": "2026-07-15T13:22:04Z",
      "play_mode": 0,
      "accuracy": 99.42,
      "pp": 412.7,
      "rank": "S",
      "beatmap": {
        "beatmap_id": 445566,
        "beatmapset_id": 221100,
        "song_name": "xi - Blue Zenith",
        "ar": 9.3, "od": 8.8, "mode": 0,
        "difficulty": 6.42,
        "difficulty2": { "std": 6.42, "taiko": 0, "ctb": 0, "mania": 0 },
        "max_combo": 1560, "hit_length": 172,
        "ranked": 2, "ranked_status_frozen": 0,
        "latest_update": "2024-01-02T00:00:00Z"
      }
    }
  ]
}

GET /scores

Returns scores set on a given beatmap.

Param	Type	Description
md5	csv string	Beatmap MD5 hash(es) — one of md5/b required
b	int	Beatmap ID (resolved to MD5 server-side)
mode / smode	int	Optional filters
p / l	int	Page number / page size (default 1 / 50)

GET /users/achievements

Returns the full achievement list for a user, each flagged with whether it's been unlocked.

GET /users/achievements?id=2

{
  "code": 200,
  "achievements": [
    { "id": 12, "name": "Rising Star", "description": "Reach 1,000 ranked score", "icon": "rising_star.png", "achieved": true }
  ]
}

GET /users/most_played

id/name + p/l (default page size 10, smaller than everything else). Returns an empty list instead of an error if the user can't be resolved.

GET /users/history

id (required), mode, rx. Returns three parallel time-series arrays: ranking_history, play_history, replays_history.

Beatmaps

GET /beatmaps

b= switches to single-object mode (returns a flat object); everything else is list mode.

Param	Type	Description
b	int	Single-beatmap mode
bb	csv int	List mode by beatmap IDs
s	csv int	List mode by beatmapset IDs
md5	csv string	List mode by MD5 hashes
song_name	string	Filter
p / l	int	Page number / page size (list mode only)

Leaderboard

GET /leaderboard / /leaderboard/score / /leaderboard/country

Param	Type	Description
mode	int	0–3 (default 0)
smode	int	0=vanilla, 1=relax (default 0)
country	string	e.g. US, JP — not available on /leaderboard/country
p / l	int	Page number / page size (default 1 / 50, capped at 500)

/leaderboard sorts by pp, /leaderboard/score by ranked score. /leaderboard/country aggregates by country instead of listing individual users:

GET /leaderboard/country?mode=0&p=1&l=50

{
  "code": 200,
  "countries": [
    { "country": "JP", "total_pp": 812345, "ranked_score": 981234567890, "playcount": 4521123, "active_users": 812, "rank": 1 }
  ],
  "total": 187
}

Clans

GET /clans

id= returns a single clan (including its owner); omitted, it lists all clans (p/l).

GET /clans/members

id (required, clan ID), m (mode), sm (sub-mode). Returns a clan's roster with per-member stats for the selected mode.

GET /clans/stats/all

m, sm, p, l (capped at 100). Returns a ranked list of clans with aggregate stats.

Multiplayer

GET /multi/matches

p/l. Returns a paginated list of multiplayer matches.

GET /multi/match

id (required). Returns full match detail, including every game played in that match.

GET /multi/matches/players

ids (csv) or id. Flat array, one entry per match/player pair — not grouped by match.

Badges

GET /badges

No params. Returns every badge defined on the server.

GET /badges/members

id (required, badge ID). Returns every user holding that badge. Note: l is accepted but currently has no effect — this endpoint always returns the full member list.

Everything else

GET /topdonors

l (default 50, capped at 100). Only includes users with an active, non-expired donor status; the amount is the sum of completed donations.

GET /stats

No params.

GET /stats

{ "code": 200, "registered_players": 18234, "online_users": 214, "total_scores": 5920341, "total_pp": 812345678 }

GET /staff

No params. Returns the current staff roster, each resolved to a role name/color:

GET /staff

{
  "code": 200,
  "staff": [
    { "id": 2, "username": "Kobo Kanaeru", "role_name": "BAT", "role_color": "danger" }
  ]
}