Skip to main content
Warning endpoints expose the warning system for the web dashboard. All endpoints require moderator-level permissions. Requests are rate-limited to 120 requests per 15 minutes per IP.

​
GET /warnings

Returns paginated warnings for a guild with optional filters. Authentication: API key or JWT Bearer token required.

​
Query parameters

​
guildId
string
required
The Discord guild ID.
​
userId
string
Filter warnings by target user ID.
​
active
boolean
Filter by active status (true or false).
​
severity
string
Filter by severity. Options: low, medium, high.
​
page
integer
Page number. Default: 1.
​
limit
integer
Items per page. Default: 25. Maximum: 100.

​
Response fields

​
warnings
array
List of warning records.
​
total
integer
Total matching warnings.
​
page
integer
Current page.
​
limit
integer
Items per page.
​
pages
integer
Total pages.

​
Example

curl -H "x-api-secret: YOUR_SECRET" \
  "https://volvox.bot/api/v1/warnings?guildId=987654321098765432&active=true&severity=high"

{
  "warnings": [
    {
      "id": 14,
      "guild_id": "987654321098765432",
      "user_id": "111000111",
      "reason": "Harassment",
      "severity": "high",
      "points": 3,
      "active": true,
      "created_at": "2026-03-19T12:00:00.000Z"
    }
  ],
  "total": 3,
  "page": 1,
  "limit": 25,
  "pages": 1
}

​
GET /warnings/user/:userId

Returns a warning summary and history for a specific user, including active warning count, total points, breakdown by severity, and the 50 most recent warnings. Authentication: API key or JWT Bearer token required.

​
Path parameters

​
userId
string
required
The Discord user ID.

​
Query parameters

​
guildId
string
required
The Discord guild ID.

​
Response fields

​
userId
string
The queried Discord user ID.
​
activeCount
integer
Number of currently active warnings.
​
activePoints
integer
Total points from active warnings.
​
bySeverity
object
Active warning count keyed by severity (for example, { "low": 1, "high": 2 }).
​
warnings
array
Up to 50 most recent warnings for this user.

​
Example

curl -H "x-api-secret: YOUR_SECRET" \
  "https://volvox.bot/api/v1/warnings/user/111000111?guildId=987654321098765432"

{
  "userId": "111000111",
  "activeCount": 3,
  "activePoints": 7,
  "bySeverity": { "low": 1, "medium": 0, "high": 2 },
  "warnings": [
    {
      "id": 14,
      "reason": "Harassment",
      "severity": "high",
      "points": 3,
      "active": true,
      "created_at": "2026-03-19T12:00:00.000Z"
    }
  ]
}

​
GET /warnings/stats

Returns aggregate warning statistics for a guild. Authentication: API key or JWT Bearer token required.

​
Query parameters

​
guildId
string
required
The Discord guild ID.

​
Response fields

​
totalWarnings
integer
All-time total number of warnings issued.
​
activeWarnings
integer
Number of currently active warnings.
​
bySeverity
object
Active warning count keyed by severity.
​
topUsers
array
Top 10 users by active warning points. Each item has user_id, count, and points.

​
Example

curl -H "x-api-secret: YOUR_SECRET" \
  "https://volvox.bot/api/v1/warnings/stats?guildId=987654321098765432"

{
  "totalWarnings": 150,
  "activeWarnings": 42,
  "bySeverity": { "low": 20, "medium": 15, "high": 7 },
  "topUsers": [
    { "user_id": "111000111", "count": 3, "points": 7 }
  ]
}

Build docs developers (and LLMs) love

Get started for freeTalk to us