Skip to main content
Temporary roles are Discord roles assigned to a member for a fixed duration. The bot automatically removes the role when the assignment expires. These endpoints expose temp role management for the web dashboard. Base path: /api/v1/temp-roles Authentication: API key or JWT Bearer token required. Moderator permission required. Rate limit: 120 requests per 15 minutes per IP.

​
GET /temp-roles

Returns a paginated list of active (non-expired) temporary role assignments for a guild.

​
Query parameters

​
guildId
string
required
The Discord guild ID to query.
​
userId
string
Filter results to a specific user ID.
​
page
integer
default:"1"
Page number.
​
limit
integer
default:"25"
Items per page. Maximum 100.

​
Response

​
data
array
List of active temp role assignment records.
​
pagination
object

​
Example

curl -H "x-api-secret: YOUR_SECRET" \
  "https://volvox.bot/api/v1/temp-roles?guildId=987654321&page=1&limit=25"

{
  "data": [
    {
      "id": 12,
      "guild_id": "987654321",
      "user_id": "111222333",
      "user_tag": "alice",
      "role_id": "444555666",
      "role_name": "VIP",
      "expires_at": "2026-03-28T10:00:00.000Z",
      "reason": "Contest winner"
    }
  ],
  "pagination": { "page": 1, "limit": 25, "total": 1, "pages": 1 }
}

​
POST /temp-roles

Assigns a temporary role to a member via the dashboard. The role is applied to the member in Discord immediately and scheduled for automatic removal.

​
Request body

​
guildId
string
required
The Discord guild ID.
​
userId
string
required
Discord user ID to assign the role to.
​
roleId
string
required
Discord role ID to assign.
​
duration
string
required
Duration string (for example, 1h, 7d, 2w). Parsed by the bot’s duration utility.
​
reason
string
Optional reason recorded in the assignment and shown in Discord audit log.

​
Response

HTTP 201 on success. Returns { "success": true, "data": <assignment record> }.

​
Example

curl -X POST \
  -H "x-api-secret: YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "guildId": "987654321",
    "userId": "111222333",
    "roleId": "444555666",
    "duration": "7d",
    "reason": "Contest winner"
  }' \
  https://volvox.bot/api/v1/temp-roles

{
  "success": true,
  "data": {
    "id": 13,
    "guild_id": "987654321",
    "user_id": "111222333",
    "role_id": "444555666",
    "expires_at": "2026-03-28T10:00:00.000Z"
  }
}

​
Error responses

StatusCause
400Missing required fields; invalid duration string; invalid guild, user, or role
401Missing authentication
403Not a guild moderator
503Discord client not available

​
DELETE /temp-roles/:id

Revokes an active temp role assignment by its database record ID. The role is removed from the member in Discord immediately.

​
Path parameters

​
id
integer
required
The database record ID of the assignment to revoke.

​
Query parameters

​
guildId
string
required
The Discord guild ID (required for permission check).

​
Response

HTTP 200 on success. Returns { "success": true, "data": <revoked record> }.

​
Example

curl -X DELETE \
  -H "x-api-secret: YOUR_SECRET" \
  "https://volvox.bot/api/v1/temp-roles/13?guildId=987654321"

​
Error responses

StatusCause
400Missing or invalid guildId; invalid record ID
404Assignment not found or already expired
403Not a guild moderator

Build docs developers (and LLMs) love

Get started for freeTalk to us