Cập nhật lần cuối
Bắt đầu
Ba bước: tạo key, gọi một endpoint, đọc provenance. Mỗi request đều được tính phí từ ví credit của workspace, chính là ví mà dashboard đang dùng.
Yêu cầu trước
- Một workspace RoomScope. Dùng miễn phí nếu bạn chưa có; gói Free có thể đọc các bảng đã lưu cache qua API.
- Một vai trò được phép quản lý key (
keys:manage). Chủ workspace mặc định có quyền này.
1. Tạo API key
Trong dashboard, mở Cài đặt → API key → Tạo key, đặt tên và chọn các scope mà key cần. Secret chỉ hiện một lần; hãy lưu nó vào trình quản lý secret của bạn. Sau đó chỉ còn thấy được tiền tố của key.
rank:read cho bảng xếp hạng).2. Gửi request đầu tiên
Lấy bảng ngày chính thức hôm nay của Việt Nam. Trước tiên, đặt biến ROOMSCOPE_API_KEY trong môi trường của bạn.
curl "https://api.next.toktokdata.live/v1/rankings/official?board=daily®ion=VN&period=current&limit=10" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY" \ -H "Accept: application/json"3. Đọc response
Mọi response thành công đều có một object data và một object provenance. Provenance cho biết tín hiệu được ghi nhận lúc nào và độ phủ đầy đủ tới đâu; hãy xem nó là một phần của kết quả, không phải metadata.
{ "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" }}Nếu bảng chưa thể công bố (publishable: false), danh sách entries sẽ trống và provenance.coverageStatus giải thích lý do. Các entry bị che (masked: true) mang gói có thể hiện tên chúng trong unmaskTier.
Bước tiếp theo
- Xác thực: scope, xoay vòng key và ý nghĩa của 401 hoặc 403.
- Lỗi: envelope lỗi và khi nào nên thử lại.
- Tham chiếu Bảng xếp hạng: mọi tham số của
GET /v1/rankings/official.