---
url: https://wiki.awmc.team/en/dev/chart-preview-api.md
---

# Chart Review & Analysis API

Public REST API for the Chart Preview platform, supporting chart queries, comments, ratings, score submissions, and rankings.

::: tip Platform

* **Base URL**: `https://v.wmc.pub/api/v1/`
* **Source**: [Pimeng/Maimai-Chart-Preview](https://github.com/Pimeng/Maimai-Chart-Preview)
  :::

::: warning 🔐 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.
:::

::: danger ⚠️ Note
API Keys are **only displayed once** at creation. If lost, you must create a new one.
:::

***

## Obtaining an API Key

1. Log in at https://v.wmc.pub
2. Click the key icon in the top navigation bar to go to `/api-keys`
3. 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

::: warning 🔐 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

::: danger 🔒 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:

```json
{
  "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

```bash
# 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"
```
