문서 목차

개발자 문서 / REST API

API 문서

한국포럼의 데몬리스트, 유저, 스탯 데이터를 조회하고 기록을 제출하는 방법을 안내합니다. 모든 요청은 /api 아래의 상대 경로입니다.

엔드포인트 13개응답 형식 JSON호출 한도 1,000회 / 30분

요청·응답 값은 설명용 예시입니다. 실제 데이터는 엔드포인트마다 다를 수 있습니다.

공통 응답

모든 응답은 status와 data로 감싸집니다. 성공 시 data의 타입은 엔드포인트마다 다르며, 실패 시에는 오류 메시지가 반환됩니다.

성공JSON

{
  "status": "success",
  "data": {
    "user_id": 101,
    "nickname": "ExamplePlayer"
  }
}

실패JSON

{
  "status": "error",
  "data": "요청 처리 실패"
}

필드	타입	설명
`status`	`string`	`success` 또는 `error`
`data`	`object \| array \| string \| integer`	응답 데이터 또는 오류 메시지

호출 제한과 인증

모든 엔드포인트는 IP 기준 30분당 1,000회로 제한됩니다. 쓰기 엔드포인트는 그보다 더 좁은 한도를 따로 두며, 각 항목의 “호출 한도”에 적어 두었습니다.

조회(GET) 엔드포인트는 인증이 없습니다. 쓰기 엔드포인트는 사이트 로그인 세션(쿠키)으로 인증하며, 사이트 화면이 쓰는 라우트를 그대로 공개한 것이라 응답이 공통 봉투 대신 { ok } / { error } 형태입니다. 내 리퀘스트 목록만 v4 와 같이 Discord OAuth2 토큰 헤더로도 부를 수 있습니다.

한도를 넘으면 429 와 함께 안내 메시지가 반환됩니다. 토큰이 만료되었으면 401 입니다.

엔드포인트

BASE /api

레벨 목록 조회

난이도 순서로 정렬된 레벨 목록을 페이지 단위로 가져옵니다.

GET/api/demonlist/levels?page=1&count=20

인증 없음호출 한도 30분당 1,000회데몬리스트

파라미터

이름	타입	필수	위치	설명
`page`	`integer`	필수	쿼리	1 이상의 페이지 번호
`count`	`integer`	필수	쿼리	한 페이지 항목 수. 1–1000

응답

data는 레벨 객체의 배열입니다. 순위, 제작·검증 유저, 인정 진행률과 100% 클리어 점수를 포함합니다.

200 OKJSON

{
  "status": "success",
  "data": [
    {
      "level_id": 123,
      "level_name": "Example Level",
      "level_rank": 1,
      "pointercrate_rank": 1,
      "is_legacy": false,
      "require_percent": 70,
      "publisher": {
        "user_id": 101,
        "nickname": "ExamplePlayer",
        "is_korean": true
      },
      "verifier": {
        "user_id": 101,
        "nickname": "ExamplePlayer",
        "is_korean": true
      },
      "creators": [
        {
          "user_id": 101,
          "nickname": "ExamplePlayer",
          "is_korean": true
        }
      ],
      "video_url": "https://www.youtube.com/watch?v=VIDEO_ID",
      "category": "year_2024,object_200000",
      "rate_point": 382,
      "rate_users": 120,
      "score": 1000
    }
  ]
}

레벨 상세 조회

레벨 ID, 순위 또는 이름으로 메타데이터와 클리어 기록·평가를 가져옵니다.

GET/api/demonlist/levels/123?find_by=id

인증 없음호출 한도 30분당 1,000회데몬리스트

레벨 이름으로 찾을 때는 대소문자를 구분합니다. 인게임 정보가 아직 수집되지 않았으면 null 일 수 있습니다.

파라미터

이름	타입	필수	위치	설명
`value`	`string \| integer`	필수	경로	찾을 레벨의 ID·순위·이름
`find_by`	`string`	선택	쿼리	id / rank / name. 기본값은 id

응답

data는 레벨 객체입니다. 아래 응답은 주요 필드만 담은 축약 예시입니다.

200 OKJSON

{
  "status": "success",
  "data": {
    "level_id": 123,
    "level_name": "Example Level",
    "level_rank": 1,
    "pointercrate_rank": 1,
    "is_legacy": false,
    "require_percent": 70,
    "publisher": {
      "user_id": 101,
      "nickname": "ExamplePlayer",
      "is_korean": true
    },
    "verifier": {
      "user_id": 101,
      "nickname": "ExamplePlayer",
      "is_korean": true
    },
    "creators": [
      {
        "user_id": 101,
        "nickname": "ExamplePlayer",
        "is_korean": true
      }
    ],
    "video_url": "https://www.youtube.com/watch?v=VIDEO_ID",
    "category": "year_2024,object_200000",
    "rate_point": 382,
    "rate_users": 120,
    "score": 1000,
    "ingame_level_id": 86407629,
    "ingame_objects": 220116,
    "highest_rank": 1,
    "warn_message": "",
    "records": [
      {
        "user": {
          "user_id": 101,
          "nickname": "ExamplePlayer",
          "is_korean": true
        },
        "percent": 100,
        "video_url": "https://www.youtube.com/watch?v=VIDEO_ID",
        "device_type": "Mobile",
        "device_fps": 120,
        "is_fps_bypass": false,
        "is_cbf": false,
        "score": 1000
      }
    ],
    "comments": [
      {
        "context": "평가 내용 예시",
        "upload_date": 1788825600,
        "user": {
          "user_id": 101,
          "nickname": "ExamplePlayer",
          "is_korean": true
        },
        "rates": 4
      }
    ]
  }
}

유저 포인트 리더보드

한국 유저를 데몬리스트 포인트 순으로 조회합니다.

GET/api/demonlist/leaderboard?page=1&count=20

인증 없음호출 한도 30분당 1,000회데몬리스트

파라미터

이름	타입	필수	위치	설명
`page`	`integer`	필수	쿼리	1 이상의 페이지 번호
`count`	`integer`	필수	쿼리	한 페이지 항목 수. 10–1000

응답

data는 순위가 정렬된 유저 배열입니다. achievements는 쉼표로 구분된 메달 값이며 trophy는 트로피 등급입니다.

200 OKJSON

{
  "status": "success",
  "data": [
    {
      "rank": 1,
      "user_id": 101,
      "nickname": "ExamplePlayer",
      "point": 17457.7,
      "achievements": "",
      "trophy": "top1"
    }
  ]
}

레벨 평가 등록

로그인한 포럼 유저의 이름으로 레벨 평가를 등록하거나 수정합니다.

POST/api/demonlist/levels/123/comments

Discord 인증 필요호출 한도 10분당 20회데몬리스트

레벨을 100% 클리어한 유저만 평가할 수 있으며, 유저별 평가는 하나만 등록할 수 있습니다. 이미 있으면 덮어쓰고 다시 검토 대기로 들어갑니다. 같은 경로에 DELETE 를 보내면 내 평가를 숨깁니다. 사이트에 로그인한 세션(쿠키)으로 인증합니다. 응답은 { ok } / { error } 형태이며 공통 봉투를 쓰지 않습니다.

파라미터

이름	타입	필수	위치	설명
`level_id`	`integer`	필수	경로	평가할 레벨의 ID (내부 level_id)
`rates`	`integer`	필수	본문	평점 값 (1–5)
`context`	`string`	필수	본문	평가 내용. 1–150자

요청 본문JSON

{
  "rates": 4,
  "context": "평가 내용 예시"
}

응답

commentId는 등록된 평가 ID, isNew는 새로 만든 것인지, notified는 운영진 알림 전송 여부입니다.

200 OKJSON

{
  "status": "success",
  "data": {
    "ok": true,
    "commentId": 567,
    "isNew": true,
    "notified": true
  }
}

스탯랭킹 조회

선택한 게임 스탯의 순위와 직전 집계 수치를 조회합니다.

GET/api/statrank/stars

인증 없음호출 한도 30분당 1,000회스탯랭킹

파라미터

이름	타입	필수	위치	설명
`stat`	`string`	필수	경로	stars / moons / demons / diamonds / coins / creator_points (cp) / extreme_demons (ed)

응답

data는 유저 배열입니다. 증감은 현재 값에서 prev_stat_value 를 빼서 계산합니다.

200 OKJSON

{
  "status": "success",
  "data": [
    {
      "rank": 1,
      "account_nickname": "ExamplePlayer",
      "stat_value": 338805,
      "ingame_rank": 18,
      "prev_stat_value": 337494,
      "prev_ingame_rank": 18,
      "account_id": 12345,
      "player_id": 67890
    }
  ]
}

ID·닉네임으로 유저 조회

포럼 유저를 조회하고 필요한 데이터 묶음만 선택해 가져옵니다.

GET/api/users/id/101?config=demonlist

인증 없음호출 한도 30분당 1,000회유저 · 계정

파라미터

이름	타입	필수	위치	설명
`find_by`	`string`	필수	경로	id 또는 name
`value`	`string \| integer`	필수	경로	유저 ID 또는 닉네임. 닉네임은 대소문자 미구분
`config`	`string`	선택	쿼리	demonlist / demonlist.records / demonlist.comments. 여러 값은 쉼표로 구분

응답

data는 유저 객체입니다. config를 생략하면 기본 정보만 반환하며, 지정하면 포인트·기록·평가 정보를 확장합니다.

200 OKJSON

{
  "status": "success",
  "data": {
    "user_id": 101,
    "nickname": "ExamplePlayer",
    "is_korean": true,
    "achievements": "",
    "demonlist": {
      "point": 17457.7,
      "rank": 1,
      "trophy": "top1"
    }
  }
}

Discord 계정 연동

로그인한 Discord 계정을 기존 포럼 유저와 연결합니다.

POST/api/me/discord-link

Discord 인증 필요호출 한도 1시간당 20회유저 · 계정

Discord 로 직접 로그인한 세션에서만 됩니다. YouTube 영상이 연결된 클리어 기록이 필요하며, Discord Connections의 YouTube 채널과 최근 기록 영상의 채널이 일치해야 합니다. 사이트에 로그인한 세션(쿠키)으로 인증합니다. 응답은 { ok } / { error } 형태이며 공통 봉투를 쓰지 않습니다.

파라미터

이름	타입	필수	위치	설명
`nickname`	`string`	필수	본문	연동할 포럼 닉네임

요청 본문JSON

{
  "nickname": "ExamplePlayer"
}

응답

userId는 연결된 포럼 유저 ID입니다. 응답과 함께 세션 쿠키가 갱신됩니다.

200 OKJSON

{
  "status": "success",
  "data": {
    "ok": true,
    "userId": 101,
    "nickname": "ExamplePlayer"
  }
}

Discord 연동 해제

Discord 계정과 포럼 유저 사이의 연동을 해제합니다.

DELETE/api/me/discord-link

Discord 인증 필요호출 한도 1시간당 5회유저 · 계정

기록과 순위는 그대로 남습니다. GD 계정 연동 해제는 DELETE /me/gd-link 입니다. 사이트에 로그인한 세션(쿠키)으로 인증합니다. 응답은 { ok } / { error } 형태이며 공통 봉투를 쓰지 않습니다.

응답

성공하면 ok 가 true 이며 세션 쿠키가 갱신됩니다.

200 OKJSON

{
  "status": "success",
  "data": {
    "ok": true
  }
}

게임 계정 연동코드 발급

Geometry Dash 계정의 소유 확인에 사용할 코드와 UUID를 발급합니다.

POST/api/me/gd-link

Discord 인증 필요호출 한도 1시간당 20회유저 · 계정

발급된 code 는 인게임 GMDKoreaForum 계정으로 보내는 메시지의 **제목**에 사용합니다. 코드는 10분 동안만 유효합니다. 사이트에 로그인한 세션(쿠키)으로 인증합니다. 응답은 { ok } / { error } 형태이며 공통 봉투를 쓰지 않습니다.

요청 본문JSON

{}

응답

code는 인게임 메시지용 코드, uuid는 아래 확인 요청에 되돌려 줄 값입니다.

200 OKJSON

{
  "status": "success",
  "data": {
    "code": "EXAMPLECODE",
    "uuid": "00000000-0000-4000-8000-000000000000"
  }
}

게임 계정 연동 확인

인게임 메시지가 도착했는지 확인하고, 보낸 GD 계정을 내 포럼 계정에 연결합니다.

POST/api/me/gd-link/verify

Discord 인증 필요호출 한도 1시간당 20회유저 · 계정

연결된 포럼 계정이 없는 세션이면 GD 계정 이름으로 포럼 계정을 찾거나 새로 만들어 함께 연결합니다. 한 GD 계정은 한 포럼 유저에만 연결됩니다. 사이트에 로그인한 세션(쿠키)으로 인증합니다. 응답은 { ok } / { error } 형태이며 공통 봉투를 쓰지 않습니다.

파라미터

이름	타입	필수	위치	설명
`uuid`	`string`	필수	본문	코드 발급 때 받은 uuid

요청 본문JSON

{
  "uuid": "00000000-0000-4000-8000-000000000000"
}

응답

account 는 확인된 GD 계정의 ID 와 이름입니다. 응답과 함께 세션 쿠키가 갱신됩니다.

200 OKJSON

{
  "status": "success",
  "data": {
    "ok": true,
    "userId": 101,
    "account": {
      "id": 12345,
      "name": "ExamplePlayer"
    }
  }
}

리퀘스트 생성

기록 등재, 스탯랭킹 등재 또는 닉네임 변경을 신청합니다.

POST/api/requests

Discord 인증 필요호출 한도 1시간당 20회리퀘스트

조건부 항목은 신청 종류에 따라 달라집니다. 기록의 주인은 로그인한 계정에 연결된 포럼 유저이며, 같은 내용의 대기중 리퀘스트가 있으면 409 로 거절됩니다. 사이트에 로그인한 세션(쿠키)으로 인증합니다. 응답은 { ok } / { error } 형태이며 공통 봉투를 쓰지 않습니다.

파라미터

이름	타입	필수	위치	설명
`type`	`integer`	필수	본문	0: 데몬리스트 기록 / 1: 스탯랭킹 등재 / 3: 닉네임 변경
`levelId`	`integer`	조건부	본문	기록 신청 대상 레벨 ID (내부 level_id)
`percent`	`integer`	조건부	본문	기록 신청의 달성 진행률
`device`	`string`	조건부	본문	기록 신청: PC / Mobile / iPad
`fps`	`integer`	조건부	본문	기록 신청의 플레이 FPS (30–65535, 2.1은 360까지)
`version`	`string`	조건부	본문	게임 버전: 2.208 / 2.2 / 2.1
`modifier`	`string`	조건부	본문	none / cbf (Click Between Frames) / fps-bypass
`video`	`URL`	조건부	본문	클리어 영상 주소 (YouTube)
`rawVideo`	`URL`	조건부	본문	무편집 원본 영상 주소 (HTTPS)
`note`	`string`	선택	본문	전달할 설명. 120자 이하
`nickname`	`string`	조건부	본문	닉네임 변경 시 새 닉네임. 1–32자
`linkUuid`	`string`	조건부	본문	스탯랭킹 신청 시 계정 확인 UUID

요청 본문JSON

{
  "type": 0,
  "levelId": 123,
  "percent": 100,
  "device": "Mobile",
  "fps": 120,
  "version": "2.208",
  "modifier": "none",
  "video": "https://www.youtube.com/watch?v=VIDEO_ID",
  "rawVideo": "https://drive.google.com/file/d/FILE_ID/view",
  "note": "기록 제출 예시"
}

응답

requestId는 접수된 리퀘스트 번호입니다. 처리 결과는 내 리퀘스트 목록에서 확인합니다.

200 OKJSON

{
  "status": "success",
  "data": {
    "ok": true,
    "requestId": 21282
  }
}

내 리퀘스트 목록

인증한 Discord 계정이 신청한 최근 리퀘스트를 최대 20건 조회합니다.

GET/api/requests/account

Discord 인증 필요호출 한도 1시간당 20회리퀘스트

사이트에 로그인한 세션(쿠키)이 있으면 헤더 없이도 됩니다. 외부에서 부를 때만 Discord 토큰 헤더를 보내세요.

파라미터

이름	타입	필수	위치	설명
`token-type`	`string`	조건부	헤더	Discord OAuth2 토큰 유형. 예: Bearer
`access-token`	`string`	조건부	헤더	Discord OAuth2 액세스 토큰

요청 헤더JSON

{
  "token-type": "Bearer",
  "access-token": "<DISCORD_ACCESS_TOKEN>"
}

응답

data는 리퀘스트 배열입니다. status는 0: 대기중, 1: 승인됨, 2: 거절됨이며 처리 전 approve_date는 null입니다. notice 는 운영진 처리 메모(거절 사유)입니다.

200 OKJSON

{
  "status": "success",
  "data": [
    {
      "request_id": 21282,
      "type": 0,
      "data": {
        "user_id": 101,
        "nickname": "ExamplePlayer",
        "level_id": 123,
        "percent": 100
      },
      "status": 0,
      "approve_date": null,
      "request_date": 1788825600000,
      "approver": null,
      "notice": null
    }
  ]
}

리퀘스트 단건 조회

리퀘스트 ID로 제출 내용과 처리 상태를 조회합니다.

GET/api/requests/21282

인증 없음호출 한도 30분당 1,000회리퀘스트

파라미터

이름	타입	필수	위치	설명
`request_id`	`integer`	필수	경로	조회할 리퀘스트 ID

응답

data는 리퀘스트 객체입니다. type은 0: 기록 등재, 1: 스탯랭킹 등재, 2: 스피드런, 3: 닉네임 변경을 뜻합니다. 무편집 원본과 전달 사항은 응답에서 제외됩니다.

200 OKJSON

{
  "status": "success",
  "data": {
    "request_id": 21282,
    "type": 0,
    "data": {
      "user_id": 101,
      "nickname": "ExamplePlayer",
      "level_id": 123,
      "percent": 100
    },
    "status": 0,
    "approve_date": null,
    "request_date": 1788825600000
  }
}

문서에 없는 값이나 오류를 찾으면 알려 주세요.Discord로 문의