Mirria HTTP API

JSON response schemas

The four lookup routes and search reuse the following serialized Rust types. Fields marked optional may be JSON null; fields marked omitted are absent when no value exists.

Beatmap

Beatmapset

GET /api/v1/beatmaps/md5/:checksum

Returns the first indexed beatmapset containing a beatmap with the supplied checksum.

Parameters

Response and statuses

200 OK — application/json; one Beatmapset object.

• 404 Not Found — no indexed beatmapset contains the checksum.
• 500 Internal Server Error — the search index lookup failed.

Lookup errors do not have a documented JSON body.

Example

curl 'https://mirror.example/api/v1/beatmaps/md5/0123456789abcdef0123456789abcdef'

GET /api/v1/beatmaps/:id

Returns one indexed beatmap difficulty by beatmap ID.

Parameters

Response and statuses

200 OK — application/json; one Beatmap object.

• 404 Not Found — the indexed beatmap was not found.
• 500 Internal Server Error — the search index lookup failed.

Lookup errors do not have a documented JSON body.

Example

curl 'https://mirror.example/api/v1/beatmaps/4662168'

GET /api/v1/beatmapsets/:id

Returns one indexed beatmapset by beatmapset ID.

Parameters

Response and statuses

200 OK — application/json; one Beatmapset object.

• 404 Not Found — the indexed beatmapset was not found.
• 500 Internal Server Error — the search index lookup failed.

Lookup errors do not have a documented JSON body.

Example

curl 'https://mirror.example/api/v1/beatmapsets/2556827'

GET /api/v1/beatmapsets/beatmap/:id

Returns the first indexed beatmapset containing the supplied beatmap ID.

Parameters

Response and statuses

200 OK — application/json; one Beatmapset object.

• 404 Not Found — no indexed beatmapset contains the beatmap ID.
• 500 Internal Server Error — the search index lookup failed.

Lookup errors do not have a documented JSON body.

Example

curl 'https://mirror.example/api/v1/beatmapsets/beatmap/4662168'

Map download

GET /api/v1/download/:id and its exact short alias GET /d/:id download an osu! beatmap archive. :id is the numeric beatmapset ID.

Parameters

The no-video variant uses the official upstream noVideo=1 option and a separate {id}_novid.osz disk file and RAM cache key, so it never collides with the default {id}.osz archive.

Streaming and cache behavior

RAM and valid disk responses are cache hits; an origin download is a miss. Cached responses and upstream misses stream with backpressure. A miss is published to disk atomically only after the complete upstream body is validated and durably written. Byte-range requests are not supported; downloads return the complete archive.

The bounded smart RAM cache is populated lazily from eligible valid disk files or bytes already flowing through a request. Every ten minutes it refreshes up to 1,000 persisted download statistics; completed downloads update the live counts immediately. Refresh does not prefetch archives. Admission under capacity pressure evicts lower-priority entries by download count, successful-download time and access order; a lower-priority incoming map cannot displace a higher-priority entry. Video variants have independent byte entries.

RAM hits clone the retained byte buffer without copying its contents. An archive larger than the configured capacity is still served and kept on disk but is not admitted to RAM. Capacity bounds bytes owned or reserved by the cache; response clones already in flight may outlive eviction.

RAM capacity configuration

The cache_size setting is read from Mirria's confy YAML configuration at API startup. It defaults to "10%". Values are trimmed and case-insensitive:

cache_size: "2048MB"
# or
cache_size: "4GB"
# or
cache_size: "10%"

• MB and GB are positive integer decimal byte units.
• A percentage must be an integer from 1% through 100% and is resolved once against total host physical memory at startup.
• Zero, missing or unknown suffixes, fractions, overflow and percentages above 100 are rejected; the API fails fast instead of running with an unintended capacity.

Successful response (200)

application/x-osu-beatmap-archive binary body.

Rate limits

Clients are identified by their direct peer IP address; forwarding headers are intentionally not trusted. Cached and non-cached downloads have independent five-second fixed windows.

• Non-cached downloads: 10 successful downloads per window.
• Cached downloads: 50 successful downloads per window.

Capacity is reserved before file or upstream work begins, preventing concurrent requests from bypassing a limit. A reservation is committed only when its response body completes successfully; upstream, cache-file, streaming or abandoned-client failures refund it.

Error responses

Examples

# Default archive, including video when the set has one
curl -OJ 'https://mirror.example/api/v1/download/2556827'

# No-video variant through the short alias
curl -OJ 'https://mirror.example/d/2556827?video=false'

GET /api/v1/search

Runs a full-text and filtered search over indexed beatmapsets. The response is the hit list itself, not a pagination envelope.

Query parameters

Arrays use indexed serde_qs syntax, for example statuses[0]=ranked&statuses[1]=loved and modes[0]=osu. Percent-encode square brackets when required by the client.

Response and statuses

200 OK — application/json; an array of Beatmapset objects. An empty search result is [].

• 400 Bad Request — malformed query syntax, type or ruleset value.
• 500 Internal Server Error — the search backend failed.

Search errors do not have a documented JSON body.

Example

curl 'https://mirror.example/api/v1/search?query=camellia&limit=10&statuses%5B0%5D=ranked&modes%5B0%5D=osu&sort=updated_desc'

[{"id":2556827,"artist":"Unlucky Morpheus","title":"Kamigami ga Koishita Gensoukyou","beatmaps":[],"pack_tags":[],"covers":{},"availability":{},"nominations_summary":{},"hype":null,"artist_unicode":null,"title_unicode":null,"creator":"tmk","user_id":1,"status":"ranked","bpm":180.0,"play_count":0,"favourite_count":0,"nsfw":false,"video":false,"storyboard":false,"is_scoreable":true,"source":"","tags":"","preview_url":"","offset":0,"spotlight":false,"ranked":1,"last_updated":"2026-08-17T15:27:44Z","submitted_date":"2026-08-17T15:27:44Z","ranked_date":null,"deleted_at":null,"can_be_hyped":false,"discussion_enabled":false,"discussion_locked":false,"legacy_thread_url":null,"track_id":null,"has_favourited":false}]

The example shows the JSON shape with representative values; real metadata and nested arrays vary by result.

GET /api/v1/cache

Returns a read-only snapshot of this API process's live RAM cache, not its disk archive directory or a mounted ramdisk. Observing the cache does not change eviction order or retain archive buffers.

Optional query parameter limit defaults to 50 and accepts integers from 1 through 100. Beatmapsets are ordered by the cache's known completed-download count descending, then ID ascending. Video and no-video payload lengths are combined into one row; their shared download count is not doubled.

Response fields

These are cache payload and budget metrics, not process RSS. Allocator overhead and buffers held only by in-flight responses after eviction are excluded. Counts include live completions and the persisted baseline known to the cache; separate API processes have separate live snapshots.

Statuses and example

200 OK — application/json, including an empty RAM cache or unavailable optional metadata. 400 Bad Request — invalid limit, with a JSON ok: false, message error.

curl 'https://mirror.example/api/v1/cache?limit=50'

{"ranking":"download_count","storage":{"used_bytes":300,"reserved_bytes":100,"total_bytes":1000,"available_bytes":600},"cache":{"map_count":2,"entry_count":3,"size_bytes":300},"metadata_available":false,"maps":[{"id":200,"title":null,"artist":null,"download_count":7,"size_bytes":200},{"id":100,"title":null,"artist":null,"download_count":3,"size_bytes":100}]}

GET /cache

Serves the minimal RAM cache dashboard as text/html; charset=utf-8. It fetches this endpoint with a limit of 50 and has a manual refresh button.

Open RAM cache status

GET /health

Returns 200 OK with the plain-text body ok once the API is listening. No parameters, authentication, shared-state locks or external dependency requests are required.

This is an HTTP liveness probe, not a Meilisearch or osu! readiness check. Dependency outages do not change its response while the HTTP server remains responsive.

Docker healthcheck

The image checks http://127.0.0.1:3000/health every 30 seconds using Alpine's bundled wget, with a 3-second request timeout, a 5-second Docker timeout, a 60-second startup grace period and 3 consecutive failures before marking the container unhealthy.

Docker Compose disables this API-only probe for the crawler, which has no HTTP listener. When running a crawler directly from the shared image, use docker run --no-healthcheck.

curl -f 'https://mirror.example/health'

GET /metrics

Returns the current Prometheus metrics exposition generated by the HTTP metrics recorder. Metric series and labels depend on observed runtime traffic.

Parameters

No path or query parameters.

Response and statuses

200 OK — Prometheus text exposition returned as text/plain; charset=utf-8. This handler defines no route-specific error status.

Example

curl 'https://mirror.example/metrics'

# HELP <metric_name> <description>
# TYPE <metric_name> counter
<metric_name>{...} <value>

GET /docs

Serves this generated, human-readable API reference.

Parameters

No path or query parameters.

Response and statuses

200 OK — text/html; charset=utf-8. This handler defines no route-specific error status.

Example

curl 'https://mirror.example/docs'