화면 모드
랭킹
| 경로 | 인증 | 설명 | |
|---|---|---|---|
| GET | /v1/leaderboards | 유저 | 리더보드 목록 |
| POST | /v1/leaderboards/{code}/scores | 유저 | 점수 제출 |
| GET | /v1/leaderboards/{code}/top | 유저 | 상위 순위 ?limit=100 |
| GET | /v1/leaderboards/{code}/me | 유저 | 내 순위와 위아래 ?around=5 |
| GET | /v1/leaderboards/{code}/seasons/{season} | 유저 | 끝난 시즌 결과 ?limit=&offset= |
| GET | /v1/leaderboards/{code}/seasons/{season}/me | 유저 | 끝난 시즌 내 순위 |
목록
GET/v1/leaderboards → { "items": [ … ] }json
{ "leaderboard": "weekly", "name": "주간 랭킹", "sort": "desc", "policy": "best",
"reset_cycle": "weekly", "season": 202647, "season_ends_at": 1795359600 }점수 제출
POST/v1/leaderboards/{code}/scores — { "score": 1530, "meta": { "stage": 3 }? }json
{ "leaderboard": "weekly", "season": 202647, "score": 1530, "submitted": 1530, "updated": true, "rank": 12, "total": 840 }score는 저장된 점수예요(최고 기록 정책이면 더 낮은 점수를 내도 그대로). updated는 기록이 바뀌었는지예요.
순위 조회
GET/v1/leaderboards/{code}/top?limit=50json
{
"leaderboard": "weekly", "season": 202647, "total": 840,
"entries": [
{ "rank": 1, "player_id": "2048", "score": 98200, "achieved_at": 1795040000, "profile": { "nick": "wk" } }
]
}profile은 그 유저가 profile 키로 공개 저장한 값이에요(없으면 null).
/v1/leaderboards/{code}/me?around=5 → 목록 정보 + me(내 항목, 기록이 없으면 null) + entries(위아래)끝난 시즌
GET/v1/leaderboards/{code}/seasons/{season} → { "total_ranked", "entries": [ … ] } — 진행 중인 시즌이면 404GET /v1/leaderboards/{code}/seasons/{season}/me → { "me": { … } | null }시즌 번호: 일간 YYYYMMDD · 주간 YYYYWW(ISO) · 월간 YYYYMM · 수동·계속은 1부터
오류
| 오류 | 뜻 |
|---|---|
404 NOT_FOUND | 없는 리더보드 / 진행 중 시즌 조회 |
422 SCORE_OUT_OF_RANGE | 허용 범위 밖 점수 |
429 SUBMIT_TOO_FAST | 제출 간격 제한 |