The maishift API gives apps read access to maimai DX song data, to the records players have made public on maishift, and, with a player's permission, to that player's own data. It is read-only, and every request needs an API key.

This page explains how to start and the rules every endpoint follows. For each endpoint's parameters and responses, see the API reference.

Getting started

1. Sign in to maishift with an account that has synced at least one record with plays.
2. In Settings › Developer, register your app and agree to the Developer Terms.
3. Issue an API key for the app. It is shown once; store it somewhere safe.
4. Send the key in the X-API-Key header with every request:

curl -H "X-API-Key: msk_…" "https://maimai.shiftpsh.com/api/v1/songs?region=intl"

Keep the key out of public code and repositories. If it leaks, revoke it in Settings › Developer and issue a new one. Each app can have two active keys, so you can switch to a new key before revoking the old one.

A mobile, desktop or browser app ships its key to every user, where it can be extracted. That's expected: the key identifies your app and its budget, it doesn't protect players, whose sign-in is protected by PKCE. Someone holding an extracted key can spend your app's budget, so revoke and replace it if that happens. When your app has a server, keep the key there.

Endpoints

The full specification is also available as OpenAPI 3.1 at /api/v1/openapi.json, which you can use to generate a client.

Conventions

Regions. Most endpoints take region: intl for the international version, jp for the Japanese one, or na for the international data as North American cabinets see it. na returns the same data as intl, except that stats/plate-difficulty follows the plate rules of North American cabinets. In both, songs North American cabinets can't select have naUnavailable: true.

Ids. Song and chart ids belong to a region. The same chart has different ids in intl and jp.

Versions. Versions are sent as integer ids, counting from 0 for the first maimai. GET /api/v1/versions gives each region's names and release dates. The kanji is the one version plates use, as in stats/plate-difficulty's prefix.

intl and jp share the ids. From DX (13) on, intl gets each version later, and a version with no intl date hasn't been released there yet. Before DX there was no separate international release, so those versions show the Japanese dates for both.

Scaled integers. Numbers that have decimals in the game are sent as integers:

• achievement is ×10000: 1005000 is 100.5000%.
• internalLevel (the chart constant) is ×10: 134 is 13.4.

Constants. Each chart says where its constant comes from in internalLevelSource:

• community: published by the community for the current version.
• maishift: set or inferred by maishift.
• estimated: not known for the current version yet. The value is an estimate from the displayed level and earlier versions, and ratings computed from it are marked ratingAccurate: false.

Times. Timestamps are ISO 8601 in UTC. addedOn is a date (YYYY-MM-DD) in Japan time, as the game counts days.

Public data only. A profile and its latest records can be read only if the player has made their profile public. Past syncs (snapshots) also need the player to have made their past records public. Otherwise the API answers 403 not_public.

Statistics

The statistics endpoints return only aggregates over players, never anyone's own records. They are recomputed on a schedule (hourly for new charts, otherwise daily or weekly), and most responses say when in computedAt.

Rating bands group players by their rating with an unfilled new-song pool filled in, so a player who hasn't played 15 new charts yet can sit in a higher band than their displayed rating.

When a group of players (a rating band, a bucket) has fewer than 5 players, its figures come back null with suppressed: true. At that size the numbers would describe particular players rather than a group. This mostly affects the very top of the rating range and charts that are new. It is a safeguard against reading individual players off a single figure, not a guarantee: figures for overlapping groups can sometimes be combined. Don't use the statistics to single out players.

How a small group shows differs a little by endpoint: stats/ratings nulls the median and top-percentile thresholds without a flag, and its histogram nulls the band's count too; stats/clear-ratios returns an empty charts; a level band whose player count isn't known yet is suppressed whatever its size. stats/plate-difficulty is an estimate built from many charts' figures and has no suppression.

Errors

Errors come with an HTTP status and a body like this:

{
  "error": {
    "code": "not_public",
    "message": "This player's records are not public."
  }
}

Never put the key in the URL: requests with a key in the query string (api_key, apikey, key or access_token) are refused.

On /me endpoints, refused tokens also carry a WWW-Authenticate header (RFC 6750): Bearer scope="…" when no token was sent, Bearer error="invalid_token" for a bad one, and Bearer error="insufficient_scope", scope="…" when it lacks the scope.

Rate limits

Each app has a budget of 120 units, refilled at 2 units per second (120 a minute). Its keys share the budget. Each request costs units by how heavy it is:

Requests to /me endpoints draw on a separate budget for each player who authorized your app, the same size as the app's, so your room grows with your players. The token and revoke endpoints each cost 1 unit of the app's budget.

Once your key is accepted, every /api/v1 response carries X-RateLimit-Limit and X-RateLimit-Remaining, errors included (except app_suspended). On /me endpoints they describe the player's budget, except for a refused access token, which costs your app 1 unit and shows the app's budget. When you run out, the API answers 429 with a Retry-After header saying how many seconds to wait. The token and revoke endpoints send only Retry-After, with slow_down.

The song list changes at most a few times a day. Cache it instead of fetching it for every request.

Credit and terms

Using the API means agreeing to the Developer Terms. In short:

• Show in your app that its data comes from maishift, and that the app is unofficial and not affiliated with SEGA.
• Don't use the data for commercial purposes.
• Use jacket images through the URLs the API gives you; don't copy or re-host them.
• Use player data only for the purpose you registered, and delete it when a player stops using your app.

Sign in with maishift (OAuth)

With a player's permission, your app can read their own data, including what they haven't made public. maishift uses the OAuth 2.0 authorization code flow with PKCE, and PKCE is required for every app.

OAuth works only while your own maishift profile is public: players can see who made an app before they connect it. Until it is, the consent page tells players the app can't be connected.

1. Register redirect URIs. In Settings › Developer, add every URI your app receives the player back at. A URI must be https, http on localhost, 127.0.0.1 or [::1] for local testing, or an app scheme in reverse-DNS form such as com.example.app:/callback. It can't contain a fragment (#) or a user name, can't point at maishift itself, and can be up to 512 characters. An app can register up to 10, and requests must use one of them exactly.

2. Send the player to maishift. Make a random code_verifier of 43–128 characters from A–Z a–z 0–9 - . _ ~, and keep it. Its code_challenge is the base64url-encoded SHA-256 of the verifier, without padding. Then open the URL below, with your app's client ID from Settings › Developer. Values must be URL-encoded (the space between scopes becomes %20); the line breaks are only for reading.

https://maimai.shiftpsh.com/oauth/authorize
  ?response_type=code
  &client_id=msc_…
  &redirect_uri=https://example.com/callback
  &scope=records offline.access
  &state=…
  &code_challenge=…
  &code_challenge_method=S256

The player signs in and sees what your app is asking for. If they allow it, they come back to your redirect URI with code and your state; if not, with error=access_denied. Check that state is the one you sent.

A request that is wrong also comes back with an error and error_description, and your state: invalid_request (PKCE missing or malformed, or a method other than S256), invalid_scope (an unknown scope) or unsupported_response_type. Some problems never come back, and the player sees an error on maishift instead: an unknown client ID, a redirect URI you haven't registered, a suspended app, your profile not being public, and on the player's side a public-computer sign-in or a banned account.

3. Exchange the code for tokens within 10 minutes. The code works once.

curl -X POST https://maimai.shiftpsh.com/api/oauth/token \
  -H "X-API-Key: msk_…" \
  -d grant_type=authorization_code \
  -d code=… \
  -d redirect_uri=https://example.com/callback \
  -d code_verifier=…

{
  "access_token": "msa_…",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "msr_…",
  "scope": "profile records offline.access"
}

The token endpoint takes form-encoded or JSON bodies. Your API key identifies the app, so client_id isn't needed here. redirect_uri must be the one you sent to /oauth/authorize. A failed exchange still uses up the code.

The token and revoke endpoints answer errors the OAuth way (RFC 6749), as { "error": "…", "error_description": "…" }:

4. Call the /me endpoints with both your API key and the access token:

curl -H "X-API-Key: msk_…" -H "Authorization: Bearer msa_…" \
  https://maimai.shiftpsh.com/api/v1/me/records

Scopes

Ask only for what your app uses: the player sees the list before they agree. The player's friend code still follows their own setting.

Tokens

An access token lasts 2 hours. Without offline.access, send the player through authorization again when it runs out.

With offline.access, the token response also has a refresh token. It expires after 90 days unused. Each use returns a new refresh token, and the old one stops working. If an old one is ever used again, maishift takes it as a leak and ends that sign-in: every token from it stops working, and the player has to authorize again on that device. Refresh one at a time, since two refreshes with the same token count as reuse. Each sign-in is separate, so a player signed in on two devices keeps the other one. A refresh can send scope to keep or narrow the granted scopes, never widen them. Narrowing away offline.access returns no new refresh token, so that sign-in ends when its access token does.

curl -X POST https://maimai.shiftpsh.com/api/oauth/token \
  -H "X-API-Key: msk_…" \
  -d grant_type=refresh_token \
  -d refresh_token=msr_…

When the player signs out of your app, send either token to POST /api/oauth/revoke (token=…, with your API key). That ends the sign-in on that device; once no sign-in is left, your app is disconnected. Players can also disconnect your app in Settings › Connected apps, which ends every sign-in. Either way, the tokens stop working: API requests get 401 invalid_token, and a refresh gets invalid_grant. Revoking answers 200 whatever token you send, so it says nothing about which tokens exist.

Player ids

/me returns a playerId. It stays the same for one player in your app and differs in every other app. Store it to recognize returning players rather than the handle, which players can change.