Chart Review & Analysis API
Public REST API for the Chart Preview platform, supporting chart queries, comments, ratings, score submissions, and rankings.
Platform
- Base URL:
https://v.wmc.pub/api/v1/ - Source: Pimeng/Maimai-Chart-Preview
🔐 Authentication
All API requests require a Bearer token in the header:
Authorization: Bearer <api-key>
To obtain an API Key: log in at https://v.wmc.pub → click the key icon in the top navigation → /api-keys page → create a new API Key.
⚠️ Note
API Keys are only displayed once at creation. If lost, you must create a new one.
Obtaining an API Key
- Log in at https://v.wmc.pub
- Click the key icon in the top navigation bar to go to
/api-keys - Click "Create", enter a name, and copy the key after creation
Endpoints
1. Charts
1.1 List Charts
1.2 Get Chart Detail
:chartKey format: {songId}:{kind}:{difficulty}, e.g. 123:dx:4
1.3 Get Chart Tags Summary
Field Descriptions:
| Field | Type | Description |
|---|---|---|
| tags.difficultyClassification | object | Difficulty class: tag=normal/water/fake; label=Normal/Inflated/Water |
| tags.difficultyClassification.estimatedLevel | float | Difficulty value predicted by regression model |
| tags.difficultyClassification.deviation | float | Deviation from official level (positive=inflated, negative=underrated) |
| tags.radarTags | array | High-score radar axes, score 0-100 |
| tags.evaluationTags | array | High-score evaluation axes (Stamina/Endurance/Star/Keyboard/High Note Count) |
| tags.features | array | Top regression feature contributions; direction=up/down indicates difficulty increase/decrease |
| tags.features.contribution | float | Feature's contribution to difficulty value (positive=adds, negative=reduces) |
| tags.patterns | array | Detected chart patterns; severity=high/mid/low |
| tags.patterns.count | int | Occurrence count of this pattern |
| tags.patterns.severity | string | high=high intensity (strength≥5), mid=medium, low=low |
Possible radarTags labels: Cross-hand, Scatter, Sweep, Finale, Circle, Large Shift, Fixed Beat, Bomb, Burst, Trill, Jump, Offset, One-stroke, Backhand
Possible evaluationTags labels: Stamina, Endurance, Star, Keyboard, High Note Count
Possible features labels: Avg Density, High Density Penalty, Peak Density, Slide Ratio, Touch Ratio, Cross-hand, Same-position Repeat, Jump Rhythm, One-stroke, Offset, Burst, Circle, Sweep
Possible patterns labels: Offset Star, Cross-hand, Trill, Jump, One-stroke, Backhand/Large Shift, Fixed Beat, Finale, Burst, Sweep, Circle, Touch Split, Scatter, Bomb
2. Comments
2.1 Get Chart Comments
3. Ratings
3.1 Get Rating Statistics
4. Scores
4.1 Get Score Submissions
5. Rankings
5.1 Get Rankings
6. Statistics
6.1 Get Global Statistics
7. API Key Management
🔐 Login Required
The following endpoints require an active login session (browser session or JWT).
7.1 Create API Key
7.2 List My API Keys
7.3 Delete API Key
8. Admin Endpoints
🔒 Admin Only
The following endpoints are restricted to administrators.
8.1 Get API Usage Statistics
8.2 Get Usage Trends
Error Responses
All endpoints return a unified error format:
{
"message": "Error message"
}| Status Code | Description |
|---|---|
| 401 | Unauthorized or invalid API Key |
| 403 | Insufficient permissions |
| 404 | Resource not found |
| 500 | Internal server error |
Quick Start
# 1. List charts
curl -H "Authorization: Bearer mk_live_xxx" \
https://v.wmc.pub/api/v1/charts
# 2. Get chart detail
curl -H "Authorization: Bearer mk_live_xxx" \
https://v.wmc.pub/api/v1/charts/123:dx:4
# 3. Get chart tags (for Bot)
curl -H "Authorization: Bearer mk_live_xxx" \
"https://v.wmc.pub/api/v1/charts/417:standard:5/tags"
# 4. Custom thresholds (high-score items only)
curl -H "Authorization: Bearer mk_live_xxx" \
"https://v.wmc.pub/api/v1/charts/417:standard:5/tags?radar_threshold=60&feature_threshold=1.0"
# 5. Get comments
curl -H "Authorization: Bearer mk_live_xxx" \
"https://v.wmc.pub/api/v1/charts/123:dx:4/comments"
# 6. Get rankings
curl -H "Authorization: Bearer mk_live_xxx" \
"https://v.wmc.pub/api/v1/rankings?sort=rating&limit=10"