최종 업데이트 2026년 11월 1일

시작하기

key 만들기, 엔드포인트 호출, 데이터 출처 확인의 세 단계면 됩니다. 모든 요청은 워크스페이스의 크레딧 지갑에서 차감되며, 대시보드도 같은 지갑을 사용합니다.

사전 준비

RoomScope 워크스페이스. 아직 없다면 무료로 시작하세요. Free 요금제에서도 API로 캐시된 보드를 조회할 수 있습니다.
key를 관리할 수 있는 역할(keys:manage). 워크스페이스 소유자에게는 기본으로 부여됩니다.

1. API key 만들기

대시보드에서 설정 → API key → key 만들기를 열고 이름을 지정한 뒤 필요한 스코프를 선택하세요. secret은 한 번만 표시되므로 secret 관리 도구에 저장하세요. 이후에는 key 접두사만 볼 수 있습니다.

key는 서버에만 두세요

브라우저 번들이나 모바일 앱에 key를 포함하지 마세요. 백엔드 프록시를 사용하고, key에는 그 프록시에 필요한 스코프만 부여하세요(예: 랭킹 보드라면 rank:read).

2. 첫 요청 보내기

오늘의 베트남 공식 일간 보드를 가져옵니다. 먼저 환경 변수에 ROOMSCOPE_API_KEY를 설정하세요.

curl "https://api.toktokdata.live/v1/rankings/official?board=daily&region=VN&period=current&limit=10" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY" \  -H "Accept: application/json"

3. 응답 읽기

성공한 모든 응답에는 data 객체와 provenance 객체가 있습니다. 데이터 출처(provenance)는 시그널이 언제 관측되었고 커버리지가 얼마나 완전했는지 알려 줍니다. 메타데이터가 아니라 결과의 일부로 다루세요.

200 OK

{  "data": {    "board": {      "publishable": true,      "periodKey": "2026-11-01",      "resetAt": "2026-11-02T00:00:00Z",      "coverage": { "completeBoards": 24, "expectedBoards": 24 },      "entries": [        {          "rank": 1,          "creatorUid": "7123456789012345678",          "uniqueId": "room.one",          "nickname": "Room One",          "score": 2410000,          "isLive": true,          "leagueClass": null,          "movement": "same",          "masked": false,          "unmaskTier": null        }      ]    }  },  "provenance": { "coverageStatus": "observed", "observedAt": "2026-11-01T09:58:12Z" }}

보드가 아직 게시 가능한 상태가 아니면(publishable: false) 항목 목록은 비어 있고, provenance.coverageStatus에서 그 이유를 알 수 있습니다. 이름이 가려진 항목(masked: true)은 unmaskTier에 이름을 공개하는 요금제를 담고 있습니다.

다음 단계

인증: 스코프, key 교체, 그리고 401 또는 403의 의미.
오류: 오류 형식과 재시도해야 하는 경우.
랭킹 레퍼런스: GET /v1/rankings/official의 모든 파라미터.

이 페이지가 도움이 되었나요?