List Ranks

GET /api/ranking-centre

Returns every rank configured in the workspace's ranking centre. Each rank links a Roblox gamepass to a target group rank — when an applicant owns the gamepass, they're eligible for the rank.

The workspace is inferred from the API key — there is no path, query, or body parameter to specify it.

Ranking Centre is Elite-tier only. Free-tier workspaces receive 402 Payment Required with an upgradeUrl pointing at the workspace's billing page. An Elite workspace with no ranks defined yet receives 200 with "ranks": [].

Headers

Prop

Type

curl https://api.rankgun.works/api/ranking-centre \
  -H "x-api-key: YOUR_API_KEY"

Response

200 OK

{
  "workspace": {
    "id": "ms78tzxrfqjkd371eewp3dcp9s7z28st",
    "groupId": 12345678,
    "tier": "elite"
  },
  "ranks": [
    {
      "id": "r4kn83xabc456def789ghi012jkl345",
      "header": "VIP Title",
      "body": "Get the VIP role and access to private channels.",
      "rankId": 50,
      "rankName": "VIP",
      "gamepassId": 12345678,
      "gamepassLink": "https://www.roblox.com/game-pass/12345678",
      "isActive": true,
      "createdAt": 1700000000,
      "updatedAt": 1710000000
    }
  ]
}

{
  "workspace": {
    "id": "ms78tzxrfqjkd371eewp3dcp9s7z28st",
    "groupId": 12345678,
    "tier": "elite"
  },
  "ranks": []
}

Errors

Every error response has the shape:

{ "success": false, "code": "MACHINE_CODE", "error": "Human message" }

`401 MISSING_API_KEY`

No x-api-key (or Authorization: Bearer / api_token) header was sent.

{
  "success": false,
  "code": "MISSING_API_KEY",
  "error": "Provide an API key via the x-api-key header."
}

`402 ELITE_REQUIRED`

The workspace is on the Free tier. The Ranking Centre is an Elite-only feature. The body includes an upgradeUrl pointing directly at the workspace's billing page.

{
  "success": false,
  "code": "ELITE_REQUIRED",
  "error": "Ranking Centre is an Elite-tier feature.",
  "upgradeUrl": "https://rankgun.works/workspace/ms78tzxrfqjkd371eewp3dcp9s7z28st/billing"
}

`403 INVALID_API_KEY`

The key was provided but is not recognised.

{
  "success": false,
  "code": "INVALID_API_KEY",
  "error": "API key is invalid or has been regenerated."
}

`403 WORKSPACE_DEACTIVATED`

The key matches a workspace, but the workspace has been deactivated and cannot make API calls.

{
  "success": false,
  "code": "WORKSPACE_DEACTIVATED",
  "error": "This workspace has been deactivated. Contact [email protected]."
}

`500 INTERNAL_ERROR`

Unhandled server error. Safe to retry with exponential backoff.

{
  "success": false,
  "code": "INTERNAL_ERROR",
  "error": "An unexpected error occurred. Try again or contact support."
}

List Ranks

Headers

Response

Top-level fields

`workspace` object

`Rank` object

Empty (Elite workspace, no ranks yet)