API Reference
Everything you need to integrate WESK RankBot into your Roblox game. All endpoints accept JSON and return JSON.
Authentication
Every request must include your API key in the X-Api-Key header. Keys look like wesk_… and are scoped to a single group. Generate and revoke keys from your dashboard.
local HttpService = game:GetService("HttpService")
local response = HttpService:RequestAsync({
Url = "https://api.wesk.cc/v1/groups/12345/promote",
Method = "POST",
Headers = {
["X-Api-Key"] = "wesk_xxxxxxxxxxxxxxxxxxxx",
["Content-Type"] = "application/json"
},
Body = HttpService:JSONEncode({
robloxUserId = 123456
})
})
/v1/groups/{groupId}/…. The group ID in the path must match the group your API key is scoped to.Set Rank
Sets a user's rank in the group to the exact rank ID specified, overwriting their current rank. Blacklisted users are rejected.
| Parameter | Type | Description |
|---|---|---|
| groupIdrequired | number | Roblox group ID — URL path segment. |
| robloxUserIdrequired | number | Roblox User ID to rank (request body). |
| rankIdrequired | number | Target rank ID (role rank, 0–255) to assign (request body). |
Promote
Applies the matching promotion ruleyou've configured in the dashboard for the user's current rank. Returns NO_MATCHING_RULE if no enabled rule applies.
| Parameter | Type | Description |
|---|---|---|
| groupIdrequired | number | Roblox group ID — URL path segment. |
| robloxUserIdrequired | number | Roblox User ID to promote (request body). |
Demote
Applies the matching demotion rulefor the user's current rank. Available on Pro and Max plans.
| Parameter | Type | Description |
|---|---|---|
| groupIdrequired | number | Roblox group ID — URL path segment. |
| robloxUserIdrequired | number | Roblox User ID to demote (request body). |
Get Rank
Returns whether the user is in the group and, if so, their current role rank ID.
| Parameter | Type | Description |
|---|---|---|
| groupIdrequired | number | Roblox group ID — URL path segment. |
| robloxUserIdrequired | number | Roblox User ID — URL path segment. |
Error Codes
Errors return a consistent JSON shape with a machine-readable code and a human-readable message.
| HTTP | Code | Description |
|---|---|---|
| 400 | BAD_REQUEST | Malformed body or params, or an Idempotency-Key reused with a different body. |
| 400 | NO_MATCHING_RULE | No enabled promote/demote rule matches the user's current rank. |
| 401 | INVALID_API_KEY | X-Api-Key header missing or not recognised. |
| 403 | FORBIDDEN | API key is not scoped to this group. |
| 403 | FEATURE_NOT_AVAILABLE | Endpoint requires a higher plan (e.g. demote). |
| 403 | USER_BLACKLISTED | Target user is blacklisted in this group. |
| 404 | GROUP_NOT_FOUND | No group exists for the given ID. |
| 409 | CONFLICT | A request with the same Idempotency-Key is still in progress. |
| 502 | ROBLOX_API_ERROR | Roblox upstream error, or the user is not a member of the group. |
Limits & Usage
Each rank, promote, and demote call counts as one request against your group's monthly allowance. The window resets on the 1st of each month (UTC). Dedicated instances (Max plan) are isolated.
| Plan | Requests / month | API keys |
|---|---|---|
| Starter | 100 | 1 |
| Pro | 1,000 | 2 |
| Max | Unlimited | Unlimited |
usage count for the current period and an overage flag. Requests still process once you pass your allowance — the overage is flagged rather than hard-blocked.Idempotency-Key header to make retries safe. A replay with the same key within 24h returns the original result instead of re-applying the rank change.Ranking Module
Open-source server-side Lua module. Drop it under ReplicatedStorage.Ranking, configure once, then call rank / promote / demote / getRank from any server script. Every call returns (ok, result) and never raises. Download it from your dashboard.
Ranking.configure({
apiKey = "wesk_xxxxxxxxxxxxxxxxxxxx",
groupId = 1234567,
})
-- Promote a player on join (example usage)
game.Players.PlayerAdded:Connect(function(player)
local ok, result = Ranking.promote(player)
if not ok then
warn("Rank failed: " .. (result.error or "unknown"))
end
end)
Application Centre
A drop-in Roblox place that renders your Application Centre as a full-screen in-game form. It pulls your questions and theme from the dashboard, binds each submission to the player's UserId so it can't be spoofed, and auto-decides on a configurable score threshold. Set questions, pass threshold, auto-rank, and experience lock from the dashboard.
AppCentre.configure({ groupId = 1234567, apiBase = "https://api.wesk.cc" })
AppCentre.startServer()
Ranking Centre
This drop-in Roblox place allows you to sell ranks from an in-game portal. It pulls offers from your dashboard's rank centre configuration and renders them in your themed place. Each offer's price, minimum rank, target rank, and more, can be set, and is binded to a gamepass, enabling you to monetize your ranks.
RankCentre.configure({ groupId = 1234567, apiBase = "https://api.wesk.cc" })
RankCentre.startServer()
Migration Kit
Export your group's rules, blacklist, webhook and module configs, and logs as a single JSON file — or restore them into another WESK group. Import accepts the WESK export format.