API Reference

Complete RankGun API reference documentation. Learn about endpoints, authentication, rate limits, and how to integrate with your applications.

Base URL

All API requests are made to:

https://api.rankgun.works

Authentication

Every request must include your workspace API key. You can find your API key in your workspace settings using the Copy API Key button.

Pass the key via the x-api-key header:

curl -X POST https://api.rankgun.works/api/roblox/promote \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"userId": 123456789}'

You can also use the Authorization: Bearer header:

Authorization: Bearer YOUR_API_KEY

Keep your API key secret. Do not expose it in client-side code or public repositories.

Rate Limits

Limit	Value
Requests per minute (per workspace)	100
Monthly rank actions (Free plan)	170
Monthly rank actions (Elite plan)	20,000

Exceeding the per-minute rate limit will result in throttled requests. Exceeding your monthly rank action limit will return a 403 error.

Error Responses

All error responses follow a consistent JSON format:

{
  "success": false,
  "error": "A description of what went wrong"
}

Status Codes

Code	Meaning
200	Success
400	Invalid request (bad `userId`, missing fields)
401	Missing API key
403	Invalid API key or monthly limit exceeded
404	Workspace not found
500	Internal server error

Legacy Endpoints

If you are migrating from RankGun V3, the old endpoints still work but are deprecated. Please update to the new /api/* routes.

Deprecated Route	New Route	Notes
`POST /roblox/promote`	`POST /api/roblox/promote`
`POST /roblox/demote`	`POST /api/roblox/demote`
`POST /roblox/set-rank`	`POST /api/roblox/setrank`	Hyphen removed in new path

Deprecated Headers

Old Header	New Header
`staff-token`	`x-api-key`
`api_token`	`x-api-key`
`api-token`	`x-api-key`

Deprecated Body Fields

Old Field	New Field
`user_id`	`userId`
`workspace_id`	(no longer needed, implicit from API key)
`rank`	`rankId`

API Reference

On this page