RoomScope

Last updated

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.

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.

2. Make your first request

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

curl "https://api.roomscope.io/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

Was this page helpful?