Skip to main content
Moderation endpoints expose case data for the web dashboard. All endpoints require moderator-level permissions (MANAGE_GUILD or ADMINISTRATOR). Requests are rate-limited to 120 requests per 15 minutes per IP.

​
GET /moderation/cases

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

​
Query parameters

​
guildId
string
required
The Discord guild ID to scope the query.
​
targetId
string
Filter cases by the target user’s Discord ID.
​
action
string
Filter by action type. Options: warn, kick, ban, mute, unmute, unban.
​
page
integer
Page number. Default: 1.
​
limit
integer
Items per page. Default: 25. Maximum: 100.
​
order
string
Sort order. Options: asc, desc. Default: desc.

​
Response fields

​
cases
array
List of moderation case objects.
​
total
integer
Total number of matching cases.
​
page
integer
Current page number.
​
limit
integer
Items per page.
​
pages
integer
Total number of pages.

​
Example

curl -H "x-api-secret: YOUR_SECRET" \
  "https://volvox.bot/api/v1/moderation/cases?guildId=987654321098765432&action=ban"

{
  "cases": [
    {
      "id": 55,
      "case_number": 42,
      "action": "ban",
      "target_id": "111000111",
      "target_tag": "baduser#0001",
      "moderator_id": "222000222",
      "moderator_tag": "mod#1234",
      "reason": "Repeated violations",
      "duration": null,
      "expires_at": null,
      "log_message_id": "9876543210987654321",
      "created_at": "2026-03-20T18:00:00.000Z"
    }
  ],
  "total": 12,
  "page": 1,
  "limit": 25,
  "pages": 1
}

​
GET /moderation/cases/:caseNumber

Returns a single moderation case by case number, including any scheduled actions. Authentication: API key or JWT Bearer token required.

​
Path parameters

​
caseNumber
integer
required
The guild-scoped case number.

​
Query parameters

​
guildId
string
required
The Discord guild ID to scope the lookup.

​
Response fields

Returns the case object fields listed above, plus:
​
guild_id
string
Discord guild ID.
​
scheduledActions
array
Pending or completed scheduled actions linked to this case.

​
Example

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

{
  "id": 55,
  "guild_id": "987654321098765432",
  "case_number": 42,
  "action": "mute",
  "target_id": "111000111",
  "target_tag": "user#0001",
  "moderator_id": "222000222",
  "moderator_tag": "mod#1234",
  "reason": "Spam",
  "duration": "7d",
  "expires_at": "2026-03-28T18:00:00.000Z",
  "created_at": "2026-03-21T18:00:00.000Z",
  "scheduledActions": [
    {
      "id": 3,
      "action": "unmute",
      "target_id": "111000111",
      "execute_at": "2026-03-28T18:00:00.000Z",
      "executed": false,
      "created_at": "2026-03-21T18:00:00.000Z"
    }
  ]
}

​
GET /moderation/stats

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

​
Query parameters

​
guildId
string
required
The Discord guild ID.

​
Response fields

​
totalCases
integer
All-time total number of mod cases.
​
last24h
integer
Cases created in the last 24 hours.
​
last7d
integer
Cases created in the last 7 days.
​
byAction
object
Case count keyed by action type (for example, { "ban": 5, "warn": 22 }).
​
topTargets
array
Top 10 most-actioned users in the last 30 days. Each item has userId, tag, and count.

​
Example

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

{
  "totalCases": 87,
  "last24h": 3,
  "last7d": 14,
  "byAction": { "warn": 50, "kick": 10, "ban": 15, "mute": 12 },
  "topTargets": [
    { "userId": "111000111", "tag": "baduser#0001", "count": 7 }
  ]
}

​
GET /moderation/user/:userId/history

Returns the full moderation history for a specific user in a guild, with a breakdown by action type. 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.
​
page
integer
Page number. Default: 1.
​
limit
integer
Items per page. Default: 25. Maximum: 100.

​
Response fields

​
userId
string
The queried Discord user ID.
​
cases
array
Paginated list of the user’s mod cases (same fields as case objects above).
​
total
integer
Total number of cases for this user.
​
page
integer
Current page.
​
limit
integer
Items per page.
​
pages
integer
Total pages.
​
byAction
object
Case count keyed by action type for this user.

​
Example

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

{
  "userId": "111000111",
  "cases": [
    {
      "id": 55,
      "case_number": 42,
      "action": "ban",
      "reason": "Repeated violations",
      "moderator_tag": "mod#1234",
      "created_at": "2026-03-20T18:00:00.000Z"
    }
  ],
  "total": 7,
  "page": 1,
  "limit": 25,
  "pages": 1,
  "byAction": { "warn": 4, "mute": 2, "ban": 1 }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us