RoVPPS API

The RoVPPS API is a HTTPS/REST API that lets you read guild data, manage Roblox group ranks, and control user XP programmatically — without needing the Discord bot.

All versioned routes are available under /v1. Use the full path https://api.rovpps.xyz/v1/{endpoint}.

Authentication

There are two authentication mechanisms depending on which route you are calling.

Guild API Keys

All /v1/ routes require a Guild API Key obtained from the API Keys tab of your server's Dashboard. Pass the key as a raw value in the Authorization header:

The key is automatically scoped to your guild — it can only access data for the guild it was created under. Attempting to call a route for a different guildId with a mismatched key returns 403 Forbidden.

Internal Bot Key

The POST /getplayerinfo route uses a separate server-level key (env.API_KEY) and is reserved for internal bot use. It is not available to third-party callers.

Rate Limiting

Response Format

Every endpoint returns a JSON object. Successful responses always include "success": true. Errors include a message field with a human-readable description.

{
"success": true,
...data
}

{
"success": false,
"message": "Reason here"
}

Routes

Guild Data

Get Guild Data

Returns the complete configuration and bind data for a guild. The open_cloud_key is never returned — only a boolean hasOpenCloudKey is exposed.

Response fields

{
"success": true,
"guildId": "123456789012345678",
"config": {
  "PrimaryGroup": 12345678,
  "VerifiedRole": ["111111111111111111"],
  "UnverifiedRole": [],
  "ManagementRole": "222222222222222222"
},
"rankbinds": { ... },
"groupbinds": { ... },
"xpbinds": [ ... ],
"custombinds": [ ... ],
"denylist": { "roblox_user": [], "roblox_group": [] },
"hasOpenCloudKey": true
}

Ranking

Prerequisite: An Open Cloud API key and a primary group must be configured for the guild. Both can be set from the server Dashboard.

Set Rank

Sets one or more Roblox users to a specific rank in the guild's primary group. Processes each user independently — partial failures are collected and returned in failedUsers without aborting the rest.

Request body

{
"userIdArray": [123456789, 987654321],
"rank": 5
}

{
"success": true,
"results": [
  {
    "userId": 123456789,
    "success": true,
    "oldRank": "Rookie",
    "newRank": "Officer"
  }
],
"failedUsers": []
}

Promote

Advances a user by exactly one rank in the primary group. Returns an error if the user is already at the highest rank.

Request body

{
"userId": 123456789
}

{
"success": true,
"userId": 123456789,
"oldRank": "Rookie",
"newRank": "Officer"
}

Demote

Moves a user back by exactly one rank in the primary group. Returns an error if the user is already at the lowest rank.

Request body

{
"success": true,
"userId": 123456789,
"oldRank": "Officer",
"newRank": "Rookie"
}

XP

XP is stored per-guild, keyed by Roblox user ID. It is separate from rank — modifying XP does not automatically trigger a rank change. Use the bot's /xp add command or the XP binds system for automatic promotion.

Get XP

Returns the current XP total for a Roblox user in a specific guild. Returns 0 if the user has no recorded XP.

Response fields

{
"success": true,
"guildId": "123456789012345678",
"robloxId": "987654321",
"xp": 1450
}

Add / Remove XP

Adds XP to a user. Pass a negative amount to subtract. The result is clamped so XP can never go below 0.

Request body

{
"robloxId": "987654321",
"amount": 250
}

{
"success": true,
"guildId": "123456789012345678",
"robloxId": "987654321",
"xp": 1700
}

Set XP

Overwrites a user's XP to an exact value, ignoring the current total. Must be ≥ 0.

Request body

{
"robloxId": "987654321",
"xp": 5000
}

{
"success": true,
"guildId": "123456789012345678",
"robloxId": "987654321",
"xp": 5000
}

Bulk Add XP

Awards (or subtracts) XP for multiple users in a single request. Useful for distributing event rewards. Each entry is processed independently — one failure does not abort the others.

Request body

{
"entries": [
  { "robloxId": "111111111", "amount": 100 },
  { "robloxId": "222222222", "amount": 250 },
  { "robloxId": "333333333", "amount": -50 }
]
}

{
"success": true,
"results": [
  { "robloxId": "111111111", "success": true, "xp": 600 },
  { "robloxId": "222222222", "success": true, "xp": 950 },
  { "robloxId": "333333333", "success": true, "xp": 200 }
],
"failedCount": 0
}

Error Reference