API Reference

Complete RankGun API reference. Authentication, rate limits, endpoints, and error handling.

The RankGun API lets you read and manage your workspace, Roblox group ranking actions, and scheduled sessions programmatically. Every endpoint is authenticated with a workspace API key via the x-api-key header.

Endpoints

Group	Description
Workspace	Fetch workspace info, usage counters, and plan limits.
Roblox	Promote, demote, and set ranks for Roblox group members.
Sessions	Read and manage scheduled sessions, participants, and attendance.

Base URL

All API requests are made to:

https://api.rankgun.works

Authentication

Every request must include your workspace API key. Find it in your workspace settings via the Copy API Key button.

Pass it 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}'

Or via an Authorization: Bearer header:

Authorization: Bearer YOUR_API_KEY

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

Timestamps

All timestamps in the RankGun public API are Unix timestamps in seconds since epoch — not milliseconds. This applies to every request body field, query parameter, and response field that represents a point in time (scheduledStartAt, scheduledEndAt, createdAt, updatedAt, invitedAt, respondedAt, lastRankAt, usageResetAt, and so on).

If you're coming from a JavaScript background, remember that Date.now() returns milliseconds. Divide by 1000 before sending it:

const scheduledStartAt = Math.floor(Date.now() / 1000);

The API will reject values that look like milliseconds (anything greater than 10,000,000,000 ≈ year 2286) with a clear error telling you to divide by 1000.

Actor Attribution (write endpoints)

Session write endpoints (POST /api/sessions, PATCH /api/sessions/{id}/status, and the participant endpoints) require an actorRobloxId field in the request body. This is the Roblox user ID of the workspace member the action is attributed to — it becomes the creator on session records and the actor on audit log entries.

The actorRobloxId must resolve to an existing member of your workspace. If it does not, the request is rejected with a 400 error. This keeps every record traceable to a real person even when the action originates from an API integration.

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 limit returns throttled responses. Exceeding the monthly rank action quota returns a 403.

Only the Roblox ranking endpoints (/api/roblox/promote, /api/roblox/demote, /api/roblox/setrank) count against your monthly rank action quota. Workspace and sessions endpoints are free to call within the per-minute rate limit.

Error Responses

All error responses share the same JSON shape:

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

Status Codes

Code	Meaning
`200`	Success
`201`	Resource created (POST endpoints)
`400`	Invalid request (bad fields, invalid transition, unknown actor)
`401`	Missing API key
`403`	Invalid API key or monthly rank limit exceeded
`404`	Resource not found. Also returned when a resource belongs to a different workspace (to avoid leaking existence)
`409`	Conflict (e.g. participant already exists on session)
`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
`POST /roblox/promote`	`POST /api/roblox/promote`
`POST /roblox/demote`	`POST /api/roblox/demote`
`POST /roblox/set-rank`	`POST /api/roblox/setrank`

Deprecated headers: staff-token, api_token, api-token — all should be replaced with x-api-key.

Deprecated body fields: user_id → userId, rank → rankId, workspace_id (no longer needed, implicit from API key).

API Reference

On this page