Última actualización
Primeros pasos
Tres pasos: crea una clave, llama a un endpoint y lee la procedencia. Cada solicitud se cobra de la billetera de créditos de tu espacio de trabajo, la misma que usa el panel.
Requisitos previos
- Un espacio de trabajo de RoomScope. Empieza gratis si todavía no tienes uno; con el plan Free puedes leer rankings en caché a través de la API.
- Un rol que pueda administrar claves (
keys:manage). Los propietarios del espacio de trabajo lo tienen de forma predeterminada.
1. Crea una clave de API
En el panel, abre Configuración → Claves de API → Crear clave, ponle un nombre y elige los alcances que necesita. El secreto se muestra una sola vez; guárdalo en tu gestor de secretos. Después solo queda visible el prefijo de la clave.
rank:read para los rankings).2. Haz tu primera solicitud
Obtén el ranking oficial diario de hoy para Vietnam. Primero define ROOMSCOPE_API_KEY en tu entorno.
curl "https://api.toktokdata.live/v1/rankings/official?board=daily®ion=VN&period=current&limit=10" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY" \ -H "Accept: application/json"3. Lee la respuesta
Cada respuesta correcta tiene un objeto data y un objeto provenance. La procedencia te dice cuándo se observó la señal y qué tan completa era la cobertura; trátala como parte del resultado, no como metadatos.
{ "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" }}Si el ranking todavía no se puede publicar (publishable: false), la lista de entradas viene vacía y provenance.coverageStatus explica el motivo. Las entradas con nombre oculto (masked: true) indican en unmaskTier el plan que las muestra.
Próximos pasos
- Autenticación: alcances, rotación y qué significa un 401 o un 403.
- Errores: el sobre de errores y cuándo reintentar.
- Referencia de rankings: cada parámetro de
GET /v1/rankings/official.