# # /api/ stuff

NEW! check out the python api wrapper

if you'd like to retrieve data from our database, you are invited to use the same endpoints meant for the frontend but in a programmatic way. currently there's no rate limits.

if you have any issues related to CloudFlare, let me know on discord. currently all api requests are routed via CF so it's possible it might block certain IPs.

as of today, you MUST pass the following parameters:

- The `X-NISE-API` header with a value of `20240218` in every request. This should prevent random shit from breaking in the future (if you keep passing it)
- The `Accept` header with a value of `application/json` (if you want JSON instead of XML)

# ## scores search

score search is based on predicates. a predicate is a list of specifications/conditions to match results. predicates can be combined with operators such as `AND` and `OR`

- ENDPOINT: `/api/search`
- METHOD: POST
- POST FORMAT: JSON only
- POST BODY: use the score search page and click on `export POST for /api/` to fabricate a request. its easier.

[!] set your request timeout to high values since some complex queries can take a while.

Example:
curl -H "X-NISE-API: 20240218" -H "Accept: application/json" -H "Content-Type: application/json" -d '{"queries":[{"predicates":[{"field":{"name":"user_rank","type":"number"},"operator":{"operatorType":"<","acceptsValues":"any"},"value":"50"},{"field":{"name":"ur","type":"number"},"operator":{"operatorType":"<","acceptsValues":"any"},"value":"120"}],"logicalOperator":"AND"}],"sorting":{"field":"user_id","order":"ASC"},"page":1}' https://nise.moe/api/search
Try it out:

# ## users search

exactly like the scores search, but for users.

- ENDPOINT: `/api/search-user`
- METHOD: POST
- POST FORMAT: JSON only
- POST BODY: use the user search page and click on `export POST for /api/` to fabricate a request. its easier.

[!] set your request timeout to high values since some complex queries can take a while.

Example:
curl -H "X-NISE-API: 20240218" -H "Accept: application/json" -H "Content-Type: application/json" -d '{"queries":[{"predicates":[{"field":{"name":"rank","type":"number"},"operator":{"operatorType":">","acceptsValues":"any"},"value":"10"},{"field":{"name":"username","type":"string"},"operator":{"operatorType":"=","acceptsValues":"any"},"value":"degenerate"}],"logicalOperator":"AND"}],"sorting":{"field":"user_id","order":"ASC"},"page":1}' https://nise.moe/api/search-user
Try it out:

# ## get single score

if you have a `replay_id`, you can retrieve all the information 'bout that score.

- ENDPOINT: `/api/score/{replay_id}`
- METHOD: GET

Example:
curl -H "X-NISE-API: 20240218" -H "Accept: application/json" https://nise.moe/api/score/3808640439
Try it out:

# ## get single replay (data)

if you have a `replay_id`, you can retrieve the data that is used for the replay viewer (replay.nise.moe)

it contains the beatmap data, the full replay data, and all calculated judgements (by circleguard)

- ENDPOINT: `/api/score/{replay_id}/replay`
- METHOD: GET

Example:
curl -H "X-NISE-API: 20240218" -H "Accept: application/json" https://nise.moe/api/score/3808640439/replay
Try it out:

# ## get single replay (.osr)

if you have a `replay_id`, you can retrieve the emulated .osr replay file.

wtf is an emulated .osr replay file? 🡒 the osu!api does NOT return a "real" replay, so we fill the rest of the details.

COMING SOON

# ## get user details

if you have an `userId` or `username`, you can retrieve everything we know 'bout that user.

>> only pass EITHER of [userId, username], not both.

- ENDPOINT: `/api/user-details`
- METHOD: POST
- POST FIELDS: userId: long〖OR〗username: str (case insensitive)
- POST FORMAT: JSON only

Example:
curl -X POST -H "X-NISE-API: 20240218" -H "Accept: application/json" -H "Content-Type: application/json" -d '{"username": "degenerate"}' https://nise.moe/api/user-details
curl -X POST -H "X-NISE-API: 20240218" -H "Accept: application/json" -H "Content-Type: application/json" -d '{"userId": 8184689}' https://nise.moe/api/user-details
Try it out:

# ## request user score update

if you have an `userId`, you can queue a request to update all scores for that user.

>> ! we rate limit this at a single update every 4 hours for each individual user.

>> this endpoint is AUTHED, you need to send your `SESSION` cookie for now. ill work on API keys or smth.

- ENDPOINT: `/api/user-queue`
- METHOD: POST
- POST FIELDS: userId: long (*required)
- POST FORMAT: JSON only

Example:
curl -X POST -H "X-NISE-API: 20240218" -H "Accept: application/json" -H "Content-Type: application/json" --cookie "SESSION=xxx" -d '{"userId": 8184689}' https://nise.moe/api/user-queue

# ## get suspicious scores

returns a list of suspicious scores (e.g. cvUR <= 25, basically /sus/)

it is not live, but rather updates every N minutes depending on server load (usually ~10 minutes)

- ENDPOINT: `/api/suspicious-scores`
- METHOD: GET

Example:
curl -H "X-NISE-API: 20240218" -H "Accept: application/json" https://nise.moe/api/suspicious-scores
Try it out:

# ## get stolen replays

returns a list of all replay pairs with < 10 similarity ratio (basically /nu/)

it is not live, but rather updates every N minutes depending on server load (usually ~10 minutes)

- ENDPOINT: `/api/similar-replays`
- METHOD: GET

Example:
curl -H "X-NISE-API: 20240218" -H "Accept: application/json" https://nise.moe/api/similar-replays
Try it out:

# ## get banlist

returns a list of all possibly* banned users
*(so users for which the osu!web page returned the `User not found! ;_;` response.)

>> page size aint configurable, it's 100 atm. maybe a TODO.

- ENDPOINT: `/api/banlist`
- METHOD: POST
- POST FIELDS: page: int (*required, starts at 1)
- POST FORMAT: JSON only

Example:
curl -X POST -H "X-NISE-API: 20240218" -H "Accept: application/json" -H "Content-Type: application/json" -d '{"page": 1}' https://nise.moe/api/banlist
Try it out:

# ## analyze replay file (.osr)

if you have an .osr file, you can analyze it and get results + an always-online static page for it.

- ENDPOINT: `/api/analyze`
- METHOD: POST
- POST FIELDS: replay: file (*required, an .osr file)

curl -X POST -H "X-NISE-API: 20240218" -H "Accept: application/json" -F "replay=@replay1.osr" https://nise.moe/api/analyze

the response will include an `id` parameter (str), which identifies the replay you've uploaded.

that id will be subsequently available at:

- WEB INTERFACE: https://nise.moe/c/{id}
- API: https://nise.moe/api/user-scores/{id} `GET`

thanks for using the api. if you have any issues or requests, let me know on discord.

plz, try to not abuse it too much.