LogoRankForge
DashboardGet API Key

API Documentation

Integrate RankForge into your Roblox games

Base URL

https://api.rankforge.top/api/v1

Authentication

Header: X-API-Key: your-key

Rate Limits

60/min per API key

10/5s burst limit

Getting Started

1

Get an API Key

Purchase a plan from our store to get your API key.

2

Add Bot to Group

Add our ranking bot to your Roblox group with a role that can rank users.

3

Enable HTTP Requests

In Roblox Studio, go to Game Settings → Security → Enable HTTP Requests.

4

Start Making Requests

Use HttpService to make requests with your API key.

Quick Start Example (Lua)

lua
local HttpService = game:GetService("HttpService")

local API_KEY = "your-api-key-here"
local BASE_URL = "https://api.rankforge.top/api/v1"

-- Check API status
local response = HttpService:RequestAsync({
    Url = BASE_URL .. "/status",
    Method = "GET"
})

local data = HttpService:JSONDecode(response.Body)
print("API Status:", data.status) -- "online"

API Endpoints

Status

GET/api/v1/status

Check API status and bot information

Response

json
{
  "success": true,
  "status": "online",
  "bot": {
    "name": "RankForgeBot",
    "userId": 123456789
  },
  "timestamp": "2025-01-01T00:00:00.000Z"
}

Ranking

POST/api/v1/rank🔐 Auth Required

Set a user's rank in your group

Request Body

json
{
  "userId": 123456789,
  "rankId": 5
}

Response

json
{
  "success": true,
  "message": "Successfully ranked user 123456789 in group 12345 to 5.",
  "performedBy": "1234567890",
  "result": { "name": "Member", "rank": 5 }
}

Lua Example

lua
local HttpService = game:GetService("HttpService")

local API_KEY = "your-api-key-here"
local BASE_URL = "https://api.rankforge.top/api/v1"

local function rankUser(userId, rankId)
    local response = HttpService:RequestAsync({
        Url = BASE_URL .. "/rank",
        Method = "POST",
        Headers = {
            ["Content-Type"] = "application/json",
            ["X-API-Key"] = API_KEY
        },
        Body = HttpService:JSONEncode({
            userId = userId,
            rankId = rankId
        })
    })
    
    return HttpService:JSONDecode(response.Body)
end

-- Example: Rank user to rank 5
local result = rankUser(123456789, 5)
print(result.success, result.message)

Group Information

GET/api/v1/groups/:groupId/roles🔐 Auth Required

Get all roles in your group

Response

json
{
  "success": true,
  "roles": [
    { "id": 123, "name": "Guest", "rank": 0 },
    { "id": 124, "name": "Member", "rank": 1 },
    { "id": 125, "name": "Admin", "rank": 255 }
  ]
}

Lua Example

lua
local HttpService = game:GetService("HttpService")

local API_KEY = "your-api-key-here"
local BASE_URL = "https://api.rankforge.top/api/v1"
local GROUP_ID = 12345

local function getGroupRoles()
    local response = HttpService:RequestAsync({
        Url = BASE_URL .. "/groups/" .. GROUP_ID .. "/roles",
        Method = "GET",
        Headers = {
            ["X-API-Key"] = API_KEY
        }
    })
    
    return HttpService:JSONDecode(response.Body)
end

-- Get all roles
local roles = getGroupRoles()
for _, role in ipairs(roles.roles) do
    print(role.name, "- Rank:", role.rank)
end
GET/api/v1/groups/:groupId/members/:userId🔐 Auth Required

Get a user's current rank in your group

Response

json
{
  "success": true,
  "userId": 123456789,
  "groupId": 12345,
  "rank": {
    "id": 5,
    "name": "Member"
  }
}

Lua Example

lua
local HttpService = game:GetService("HttpService")

local API_KEY = "your-api-key-here"
local BASE_URL = "https://api.rankforge.top/api/v1"
local GROUP_ID = 12345

local function getUserRank(userId)
    local response = HttpService:RequestAsync({
        Url = BASE_URL .. "/groups/" .. GROUP_ID .. "/members/" .. userId,
        Method = "GET",
        Headers = {
            ["X-API-Key"] = API_KEY
        }
    })
    
    return HttpService:JSONDecode(response.Body)
end

-- Get user's rank
local userRank = getUserRank(123456789)
print("Rank:", userRank.rank.name, "(" .. userRank.rank.id .. ")")

Error Codes

CodeDescription
400Bad Request - Invalid parameters or request body
401Unauthorized - Missing API key
403Forbidden - Invalid or expired API key
429Too Many Requests - Rate limit exceeded (check Retry-After header)
500Internal Server Error - Something went wrong

Error Response Format

json
{
  "success": false,
  "message": "Error description here"
}

Rate Limiting

Limits

  • Per API Key60 requests/minute
  • Per IP (no auth)120 requests/minute
  • Burst Protection10 requests/5 seconds

Response Headers

  • X-RateLimit-LimitMaximum requests allowed per window
  • X-RateLimit-RemainingRemaining requests in current window
  • X-RateLimit-ResetSeconds until the rate limit resets
  • Retry-AfterSeconds to wait before retrying (on 429)

Rate Limit Exceeded Response (429)

json
{
  "success": false,
  "message": "Too many requests — please slow down.",
  "retryAfter": 45,
  "limit": "60 requests/minute per API key"
}

💡 Tip: Always check the X-RateLimit-Remaining header to avoid hitting rate limits. Implement exponential backoff when you receive a 429 response.

Need Help?

Join our Discord server for support, feature requests, and to connect with other developers using RankForge.

Join DiscordGo to Dashboard