Viscra

Public API Documentation

Overview

Documentation for the public API available at https://viscra.uk/api. The public API is designed for external systems to interact with your server data using a valid public API key.

All endpoints require a valid API key in the Authorization header and the target serverId either as a query parameter or inside the JSON body, this can be gained via the apikeys command.

Authentication

Every request must provide:

  • Authorization: <api-key>
  • serverId in query string or request body

Request handling validates the public API key against the server configuration stored in ServerConfig.ApiKeys.public.hash. On success, the handler populates Request.ServerConfig for downstream use.

Authentication errors

  • 400 Bad Request – missing serverId
  • 401 Unauthorized – missing Authorization header
  • 403 Forbidden – invalid API key
  • 404 Not Found – server configuration not found
  • 500 Internal Server Error – error during authentication

Rate Limiting

The public API is protected by two rate limiters:

  • Global public API limiter: 500 requests per minute per server namespace
  • Per-IP limiter: 100 requests per minute per IP address

When limits are exceeded, the API returns:

{ "error": "Too many requests, please try again after a minute." }

GET /api/server-info

Returns basic Discord guild information for the configured server.

Query parameters

  • serverId (required)

Response

{
  "id": "",
  "name": "",
  "memberCount": ,
  "iconUrl": ""
}

Errors

  • 404 Not Found – bot is not in this guild
  • 500 Internal Server Error – failed to fetch server info

GET /api/is-verified

Checks whether a Roblox user is verified in the system.

Parameters

  • robloxId (required)
  • serverId (required)

Response

{ "isVerified": true|false, "discordId": "|null" }

Errors

  • 400 Bad Request – missing robloxId
  • 500 Internal Server Error – database error

GET /api/user-xp

Returns XP for a verified Roblox user in the current server.

Parameters

  • robloxId (required)
  • serverId (required)

Response

{ "xp":  }

Errors

  • 400 Bad Request – missing robloxId
  • 500 Internal Server Error – database error

GET /api/user-rank

Returns the Roblox rank information for a user in the configured main group.

Parameters

  • robloxId (required)
  • serverId (required)

This endpoint uses the server configuration value EPConfig.MainGroupID or PromotionGroupId.

Response

{
  "groupId": ,
  "rankName": "",
  "rankId": 
}

Errors

  • 400 Bad Request – missing robloxId
  • 404 Not Found – no main group configured for this server
  • 500 Internal Server Error – failed to fetch user rank

Group Management

Manage Roblox group requests and promotions for configured groups.

GET /api/group/list-requests

Lists pending group join requests for a Roblox group.

Parameters

  • serverId (required)
  • groupId (optional) – falls back to PromotionGroupId or EPConfig.MainGroupID

Response

200 OK returns the result of GetJoinRequests.

Errors

  • 400 Bad Request – missing groupId
  • 401 Unauthorized – failed to retrieve access token

POST /api/group/accept-request

Accepts a pending group join request.

Body

  • requestId (required)
  • groupId (optional)
  • serverId (required if not in query)

Response

200 OK returns the result of HandleGroupRequest.

Errors

  • 400 Bad Request – missing groupId or requestId
  • 401 Unauthorized – failed token retrieval

POST /api/group/decline-request

Declines a pending group join request.

Body

  • requestId (required)
  • groupId (optional)
  • serverId (required if not in query)

Response

200 OK returns the result of HandleGroupRequest.

Errors

  • 400 Bad Request – missing groupId or requestId
  • 401 Unauthorized – failed token retrieval

POST /api/group/deny-request

This endpoint is an alias of /api/group/decline-request and reroutes internally to the decline handler.

Body

  • Same as /api/group/decline-request

POST /api/group/promote

Promotes a user to the next role in the configured Roblox group.

Body

  • robloxId (required)
  • groupId (optional)
  • serverId (required if not in query)

Behavior

  • Fetches current rank
  • Determines next role by sorting group roles by rank
  • Promotes to the next role if available
  • Logs rank change if successful

Response

200 OK returns the result of RankPlayer.

Errors

  • 400 Bad Request – missing groupId or robloxId, user not in group, or already at highest rank
  • 401 Unauthorized – failed token retrieval
  • 500 Internal Server Error

POST /api/group/demote

Demotes a user to the previous role in the configured Roblox group.

Body

  • robloxId (required)
  • groupId (optional)
  • serverId (required if not in query)

Behavior

  • Fetches current rank
  • Determines previous role by sorting group roles by rank
  • Demotes to the previous role unless user is already at the lowest possible rank
  • Logs rank change if successful

Response

200 OK returns the result of RankPlayer.

Errors

  • 400 Bad Request – missing groupId or robloxId, user not in group, or already at lowest possible rank
  • 401 Unauthorized – failed token retrieval
  • 500 Internal Server Error

Medal Management

Endpoints for reading and modifying awarded medals for verified users.

GET /api/medals/list

Returns the configured medal definitions for the server.

Response

{ "medals": [] }

GET /api/medals/user

Returns awarded medals for a verified Roblox user.

Parameters

  • robloxId (required)
  • serverId (required)

Response

{ "medals": [] }

Errors

  • 400 Bad Request – missing robloxId
  • 404 Not Found – user not found or not verified
  • 500 Internal Server Error

POST /api/medals/award

Awards a medal to a verified Roblox user.

Body

  • robloxId (required)
  • medalName (required)
  • serverId (required if not in query)

Response

{ "success": true, "message": "Awarded  to ." }

Errors

  • 400 Bad Request – missing robloxId or medalName
  • 404 Not Found – medal not found on server, or user not found or not verified
  • 500 Internal Server Error

POST /api/medals/revoke

Revokes a medal from a verified Roblox user.

Body

  • robloxId (required)
  • medalName (required)
  • serverId (required if not in query)

Response

{ "success": true, "message": "Revoked  from ." }

Errors

  • 400 Bad Request – missing robloxId or medalName
  • 404 Not Found – user not found or not verified, or medal not previously awarded
  • 500 Internal Server Error

Certification Management

Endpoints for reading and modifying certifications for verified users.

GET /api/certifications/list

Returns the configured certifications for the server.

Response

{ "certifications": [] }

GET /api/certifications/user

Returns awarded certifications for a verified Roblox user.

Parameters

  • robloxId (required)
  • serverId (required)

Response

{ "certifications": [] }

Errors

  • 400 Bad Request – missing robloxId
  • 404 Not Found – user not found or not verified
  • 500 Internal Server Error

GET /api/certifications/has

Checks whether a verified Roblox user has a specific certification reference.

Parameters

  • robloxId (required)
  • reference (required)
  • serverId (required)

Response

{ "hasCertification": true|false }

Errors

  • 400 Bad Request – missing robloxId or reference
  • 500 Internal Server Error

POST /api/certifications/award

Awards a certification to a verified Roblox user.

Body

  • robloxId (required)
  • reference (required)
  • serverId (required if not in query)

Response

{ "success": true, "message": "Awarded  () to ." }

Errors

  • 400 Bad Request – missing robloxId or reference
  • 404 Not Found – certification not found on server, or user not found or not verified
  • 500 Internal Server Error

POST /api/certifications/revoke

Revokes a certification from a verified Roblox user.

Body

  • robloxId (required)
  • reference (required)
  • serverId (required if not in query)

Response

{ "success": true, "message": "Revoked  from ." }

Errors

  • 400 Bad Request – missing robloxId or reference
  • 404 Not Found – user not found or not verified, or certification not awarded
  • 500 Internal Server Error

EP Management

Endpoints for EP status and EP unit management.

GET /api/ep/status

Returns EP status and warning levels for a verified Roblox user.

Parameters

  • robloxId (required)
  • serverId (required)

Response

{ "ep": { ... }, "warningLevel":  }

Errors

  • 400 Bad Request – missing robloxId
  • 404 Not Found – user not found or not verified
  • 500 Internal Server Error

POST /api/ep/add

Adds EP units to a verified Roblox user.

Body

  • robloxId (required)
  • amount (required)
  • company (required)
  • serverId (required if not in query)

Behavior

  • Requires EPConfig.Enabled to be true
  • Requires EPConfig.Units[company] to exist
  • Increments guildData.<serverId>.EP.<company> by the requested amount

Response

{ "success": true, "message": "Added  EP to  for ." }

Errors

  • 400 Bad Request – missing required fields, EP system disabled, or invalid company unit
  • 404 Not Found – user not found or not verified
  • 500 Internal Server Error

LOA Management

Endpoints for leave-of-absence status and controls.

GET /api/loa/status

Returns leave-of-absence status for a verified Roblox user.

Parameters

  • robloxId (required)
  • serverId (required)

Response

{ "active": true|false, "endsAt": , "startedAt":  }

Errors

  • 400 Bad Request – missing robloxId
  • 404 Not Found – user not found or not verified
  • 500 Internal Server Error

POST /api/loa/start

Starts LOA for a verified Roblox user.

Body

  • robloxId (required)
  • days (required)
  • serverId (required if not in query)

Response

{ "success": true, "endsAt":  }

Errors

  • 400 Bad Request – missing robloxId or days
  • 404 Not Found – user not found or not verified, or guild not found
  • 500 Internal Server Error

POST /api/loa/end

Ends LOA for a verified Roblox user.

Body

  • robloxId (required)
  • serverId (required if not in query)

Response

{ "success": true, "message": "LOA ended." }

Errors

  • 400 Bad Request – missing robloxId
  • 404 Not Found – user not found or not verified, or guild not found
  • 500 Internal Server Error

Server Startup

The public API listens on the port configured by BotConfigs.PublicReceiverPort. The Express app uses JSON bodies via express.json().

Notes

  • serverId is always required for authorization and many endpoint operations.
  • Roblox identifiers are passed as robloxId in query or body.
  • Many endpoints rely on Database.UsersCollection and verified user records.
  • Request.ServerConfig is available after successful authentication.