Get Rank
Fetch one gamepass-linked rank reward from your workspace's ranking centre.
GET /api/ranking-centre/ranks/{rankId}Returns a single rank from the workspace's ranking centre. To discover rank IDs in the first place, call GET /api/ranking-centre.
Ranking Centre is Elite-tier only. Free-tier workspaces receive 402 Payment Required with an upgradeUrl pointing at the workspace's billing page.
Headers
Prop
Type
Path Parameters
Prop
Type
curl https://api.rankgun.works/api/ranking-centre/ranks/r4kn83xabc456def789ghi012jkl345 \
-H "x-api-key: YOUR_API_KEY"Response
200 OK
{
"workspace": {
"id": "ms78tzxrfqjkd371eewp3dcp9s7z28st",
"groupId": 12345678,
"tier": "elite"
},
"rank": {
"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
}
}Top-level fields
Prop
Type
rank object
Prop
Type
Errors
Every error response has the shape:
{ "success": false, "code": "MACHINE_CODE", "error": "Human message" }400 INVALID_RANK_ID
The rankId in the URL is not a valid Convex ID format (wrong length or wrong character set).
{
"success": false,
"code": "INVALID_RANK_ID",
"error": "rankId must be a valid Convex ID."
}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 body includes an upgradeUrl pointing 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]."
}404 RANK_NOT_FOUND
No rank with that id exists, or the rank exists in a different workspace. We deliberately do not distinguish these two cases — returning a different error for "exists in another workspace" would leak the existence of ranks across workspaces.
{
"success": false,
"code": "RANK_NOT_FOUND",
"error": "No rank with id r4kn83xabc456def789ghi012jkl345 exists in this workspace."
}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."
}