Guilds - Volvox.Bot

GET /guilds

Returns the list of guilds the caller has access to.

API key callers: returns all guilds the bot is in.
OAuth users: returns guilds where the user has MANAGE_GUILD or ADMINISTRATOR. Bot owners see all guilds.

Authentication: API key or JWT Bearer token required.

Example

curl -H "x-api-secret: YOUR_SECRET" \
  https://volvox.bot/api/v1/guilds

[
  {
    "id": "987654321098765432",
    "name": "My Server",
    "icon": "https://cdn.discordapp.com/icons/987654321/abc.png",
    "memberCount": 512,
    "access": "admin"
  }
]

Response fields

string

Discord guild ID.

name

string

Guild name.

icon

string | null

Guild icon URL, or null if no icon is set.

memberCount

integer

Total number of members in the guild.

access

string

Access level. One of admin, moderator, or bot-owner. Only present for OAuth users.

GET /guilds/:id

Returns detailed information about a specific guild. Authentication: API key or JWT Bearer token required. OAuth users must have ADMINISTRATOR permission.

Path parameters

string

required

The Discord guild ID.

Response fields

string

Discord guild ID.

name

string

Guild name.

icon

string | null

Guild icon URL.

memberCount

integer

Total number of members.

channelCount

integer

Total number of channels in the guild.

channels

array

List of channels (capped at 500). Each item has id, name, type (Discord channel type enum: 0=Text, 2=Voice, 4=Category, 5=Announcement, 13=Stage, 15=Forum, 16=Media), parentId, and position.

Example

curl -H "x-api-secret: YOUR_SECRET" \
  https://volvox.bot/api/v1/guilds/987654321098765432

{
  "id": "987654321098765432",
  "name": "My Server",
  "icon": "https://cdn.discordapp.com/icons/987654321/abc.png",
  "memberCount": 512,
  "channelCount": 24,
  "channels": [
    { "id": "111222333", "name": "general", "type": 0, "parentId": null, "position": 0 }
  ]
}

GET /guilds/:id/channels

Returns all channels in the guild (capped at 500). Authentication: API key or JWT Bearer token required. OAuth users must have ADMINISTRATOR permission.

Path parameters

string

required

The Discord guild ID.

Response fields

Returns an array of channel objects with id, name, type, parentId, and position.

Example

curl -H "x-api-secret: YOUR_SECRET" \
  https://volvox.bot/api/v1/guilds/987654321098765432/channels

[
  { "id": "111222333", "name": "general", "type": 0, "parentId": "999888777", "position": 1 },
  { "id": "444555666", "name": "announcements", "type": 5, "parentId": null, "position": 0 }
]

GET /guilds/:id/roles

Returns all roles in the guild (capped at 250). The @everyone role is excluded. Authentication: API key or JWT Bearer token required. OAuth users must have ADMINISTRATOR permission.

Path parameters

string

required

The Discord guild ID.

Response fields

Returns an array of role objects.

string

Role ID.

name

string

Role name.

color

integer

Role color as a decimal integer (for example, 16711680 for red #FF0000).

Example

curl -H "x-api-secret: YOUR_SECRET" \
  https://volvox.bot/api/v1/guilds/987654321098765432/roles

[
  { "id": "123123123", "name": "Moderator", "color": 3447003 },
  { "id": "456456456", "name": "Member", "color": 0 }
]

GET /guilds/:id/config

Returns per-guild configuration (global defaults merged with guild overrides). Sensitive fields are masked. Authentication: API key or JWT Bearer token required. OAuth users must have ADMINISTRATOR permission.

Path parameters

string

required

The Discord guild ID.

Example

curl -H "x-api-secret: YOUR_SECRET" \
  https://volvox.bot/api/v1/guilds/987654321098765432/config

{
  "guildId": "987654321098765432",
  "ai": { "enabled": true, "model": "claude-3" },
  "moderation": { "logChannelId": "111222333" }
}

PATCH /guilds/:id/config

Updates per-guild configuration overrides. Only writable config sections are accepted. Authentication: API key or JWT Bearer token required. OAuth users must have ADMINISTRATOR permission.

Path parameters

string

required

The Discord guild ID.

Request body

(config sections)

object

required

A JSON object containing writable config sections to update (for example, ai, welcome, spam, moderation, triage). Values are merged leaf-by-leaf into the existing config.

Example

curl -X PATCH \
  -H "x-api-secret: YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"ai": {"model": "claude-3-5-sonnet"}}' \
  https://volvox.bot/api/v1/guilds/987654321098765432/config

{
  "enabled": true,
  "model": "claude-3-5-sonnet"
}

GET /guilds/:id/stats

Returns aggregate statistics for a guild — member count, AI conversations, moderation cases, and uptime. Authentication: API key or JWT Bearer token required. OAuth users must have ADMINISTRATOR permission.

Path parameters

string

required

The Discord guild ID.

Response fields

guildId

string

Discord guild ID.

memberCount

integer

Total members in the guild.

aiConversations

integer

Total AI conversations logged for this guild.

moderationCases

integer

Total moderation cases for this guild.

uptime

number

Bot process uptime in seconds.

Example

curl -H "x-api-secret: YOUR_SECRET" \
  https://volvox.bot/api/v1/guilds/987654321098765432/stats

{
  "guildId": "987654321098765432",
  "memberCount": 512,
  "aiConversations": 3241,
  "moderationCases": 87,
  "uptime": 432000
}

GET /guilds/:id/analytics

Returns time-series analytics data for dashboard charts — messages, joins/leaves, active members, AI usage, XP distribution, channel activity, command usage, and more. Authentication: API key or JWT Bearer token required. OAuth users must have ADMINISTRATOR permission.

Path parameters

string

required

The Discord guild ID.

Query parameters

range

string

Preset time range. Options: today, week, month, custom. Default: week.

from

string

Start of a custom date range in ISO 8601 format. Required when range=custom.

string

End of a custom date range in ISO 8601 format. Required when range=custom. Maximum span is 90 days.

interval

string

Bucket size for time-series data. Options: hour, day. Auto-selected based on range if omitted.

compare

string

When set to 1, true, yes, or on, includes comparison data for the previous equivalent period.

channelId

string

Filter analytics to a specific channel ID.

Example

curl -H "x-api-secret: YOUR_SECRET" \
  "https://volvox.bot/api/v1/guilds/987654321098765432/analytics?range=week&compare=1"

{
  "guildId": "987654321098765432",
  "range": { "type": "week", "from": "2026-03-14T00:00:00.000Z", "to": "2026-03-21T00:00:00.000Z", "interval": "day" },
  "kpis": { "totalMessages": 4821, "aiRequests": 312, "aiCostUsd": 0.48, "activeUsers": 93, "newMembers": 14 },
  "messageVolume": [
    { "bucket": "2026-03-14T00:00:00.000Z", "label": "Mar 14", "messages": 620, "aiRequests": 40 }
  ]
}

GET /guilds/:id/moderation

Returns recent moderation cases for the guild overview. Requires moderator permissions. Authentication: API key or JWT Bearer token required. OAuth users must have MANAGE_GUILD or ADMINISTRATOR permission.

Path parameters

string

required

The Discord guild ID.

Query parameters

page

integer

Page number. Default: 1.

limit

integer

Items per page. Default: 25. Maximum: 100.

Example

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

{
  "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",
      "created_at": "2026-03-20T18:00:00.000Z"
    }
  ],
  "total": 87,
  "page": 1,
  "limit": 10
}

POST /guilds/:id/actions

Triggers a bot action on a guild. The only supported action is sendMessage, which posts a text message to a channel.

This endpoint requires API key authentication only. OAuth Bearer tokens are not accepted.

Path parameters

string

required

The Discord guild ID.

Request body

action

string

required

The action to perform. Currently only sendMessage is supported.

channelId

string

required

The Discord channel ID to send the message to.

content

string

required

The message text to send. Maximum 10,000 characters.

Example

curl -X POST \
  -H "x-api-secret: YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"action": "sendMessage", "channelId": "111222333", "content": "Hello from the API!"}' \
  https://volvox.bot/api/v1/guilds/987654321098765432/actions

{
  "id": "1234567890123456789",
  "channelId": "111222333",
  "content": "Hello from the API!"
}

Overview

Endpoints

​GET /guilds

​Example

​Response fields

​GET /guilds/:id

​Path parameters

​Response fields

​Example

​GET /guilds/:id/channels

​Path parameters

​Response fields

​Example

​GET /guilds/:id/roles

​Path parameters

​Response fields

​Example

​GET /guilds/:id/config

​Path parameters

​Example

​PATCH /guilds/:id/config

​Path parameters

​Request body

​Example

​GET /guilds/:id/stats

​Path parameters

​Response fields

​Example

​GET /guilds/:id/analytics

​Path parameters

​Query parameters

​Example

​GET /guilds/:id/moderation

​Path parameters

​Query parameters

​Example

​POST /guilds/:id/actions

​Path parameters

​Request body

​Example

Build docs developers (and LLMs) love

GET /guilds

Example

Response fields

GET /guilds/:id

Path parameters

Response fields

Example

GET /guilds/:id/channels

Path parameters

Response fields

Example

GET /guilds/:id/roles

Path parameters

Response fields

Example

GET /guilds/:id/config

Path parameters

Example

PATCH /guilds/:id/config

Path parameters

Request body

Example

GET /guilds/:id/stats

Path parameters

Response fields

Example

GET /guilds/:id/analytics

Path parameters

Query parameters

Example

GET /guilds/:id/moderation

Path parameters

Query parameters

Example

POST /guilds/:id/actions

Path parameters

Request body

Example