Skip to main content
The Volvox.Bot REST API gives you programmatic access to guild management, moderation, AI conversations, community features, analytics, and more.

​
Base URL

https://volvox.bot/api/v1
All endpoints are relative to this base URL.

​
Authentication

The API supports two authentication methods. Most endpoints accept either one.
MethodHeaderNotes
API keyx-api-secret: <secret>Set via BOT_API_SECRET env var
JWT BearerAuthorization: Bearer <token>Obtained via Discord OAuth2
A small set of community and health endpoints are public and require no authentication. See the Authentication page for the full list.

Authentication

How to obtain and use API keys and JWT tokens.

Rate limits

Rate limit headers, windows, and 429 handling.

​
Response format

All responses are JSON. Successful responses return the resource directly or a wrapper object documented per endpoint.

​
Success

{
  "id": "123456789",
  "name": "My Guild",
  "memberCount": 512
}

​
Error

Errors follow a consistent shape: 
{
  "error": "Human-readable error message"
}
Validation errors may include a details array: 
{
  "error": "Config validation failed",
  "details": ["\"ai.model\" is not a writable config section"]
}

​
Error codes

StatusMeaning
400Bad request — missing or invalid parameters
401Unauthorized — missing or invalid credentials
403Forbidden — valid credentials but insufficient permissions
404Not found — resource does not exist
429Too many requests — rate limit exceeded
500Internal server error
503Service unavailable — database or external service down

​
Pagination

Paginated endpoints accept page and limit query parameters and return a wrapper with total and page fields.
ParameterTypeDefaultMax
pageinteger1—
limitinteger25100
curl -H "x-api-secret: YOUR_SECRET" \
  "https://volvox.bot/api/v1/moderation/cases?guildId=123456789&page=2&limit=50"

{
  "cases": [...],
  "total": 143,
  "page": 2,
  "limit": 50,
  "pages": 3
}
The member list endpoint uses cursor-based pagination via the after parameter instead of page/limit.

Build docs developers (and LLMs) love

Get started for freeTalk to us