Cập nhật lần cuối 1 thg 11, 2026

Get started

Three steps: create a key, call an endpoint, read the provenance. Every request is metered from your workspace’s credit wallet, the same one the dashboard uses.

Tài liệu kỹ thuật hiện chỉ có bằng tiếng Anh.

Prerequisites

A RoomScope workspace. Start free if you do not have one; the Free tier can read cached boards through the API.
A role that may manage keys (keys:manage). Workspace owners have it by default.

1. Create an API key

In the dashboard open Settings → API keys → Create key, give it a name and pick the scopes it needs. The secret is shown once; store it in your secret manager. Afterwards only the key prefix is visible.

Keep keys server-side

Never ship a key in a browser bundle or a mobile app. Use a backend proxy and give the key only the scopes that proxy needs (rank:read for leaderboards, for example).

2. Make your first request

Fetch today’s official daily board for Vietnam. Set ROOMSCOPE_API_KEY in your environment first.

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. Read the response

Every successful response has a data object and a provenance object. Provenance tells you when the signal was observed and how complete the coverage was; treat it as part of the result, not metadata.

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" }}

If the board is not publishable yet (publishable: false), the entries list is empty and provenance.coverageStatus explains why. Masked entries (masked: true) carry the tier that unmasks them in unmaskTier.

Next steps

Authentication: scopes, rotation and what a 401 or 403 means.
Errors: the error envelope and when to retry.
Rankings reference: every parameter of GET /v1/rankings/official.

Trang này có hữu ích không?