Conversations

Conversation endpoints let you browse AI chat history, view conversation analytics, flag problematic messages, and review the flag queue. All endpoints require admin-level permissions (ADMINISTRATOR). Requests are rate-limited to 60 requests per minute per IP.

GET /guilds/:id/conversations

Returns AI conversations grouped by channel and time proximity. Messages within 15 minutes in the same channel are grouped into a single conversation. Defaults to the last 30 days. Authentication: API key or JWT Bearer token required.

Path parameters

string

required

The Discord guild ID.

Query parameters

page

integer

Page number. Default: 1.

limit

integer

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

string

Full-text search in message content.

user

string

Filter by exact username.

channel

string

Filter by channel ID.

from

string

Start date filter in ISO 8601 format. Defaults to 30 days ago if omitted.

string

End date filter in ISO 8601 format.

Response fields

conversations

array

List of grouped conversation summaries.

Show Conversation object fields

integer

ID of the first message in the conversation.

channelId

string

Discord channel ID.

channelName

string | null

Human-readable channel name from the Discord cache.

participants

array

List of { username, role } objects for all participants.

messageCount

integer

Total messages in the conversation.

firstMessageAt

string

ISO 8601 timestamp of the first message.

lastMessageAt

string

ISO 8601 timestamp of the most recent message.

preview

string

First 100 characters of the opening message.

total

integer

Total number of matching conversations.

page

integer

Current page.

Example

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

{
  "conversations": [
    {
      "id": 10042,
      "channelId": "111222333",
      "channelName": "ai-chat",
      "participants": [
        { "username": "alice", "role": "user" },
        { "username": "Volvox", "role": "assistant" }
      ],
      "messageCount": 6,
      "firstMessageAt": "2026-03-20T14:00:00.000Z",
      "lastMessageAt": "2026-03-20T14:12:00.000Z",
      "preview": "How do I deploy to Kubernetes?"
    }
  ],
  "total": 1,
  "page": 1
}

GET /guilds/:id/conversations/stats

Returns aggregate statistics about AI conversations for the guild. Authentication: API key or JWT Bearer token required.

Path parameters

string

required

The Discord guild ID.

Response fields

totalConversations

integer

Total number of distinct conversations.

totalMessages

integer

Total number of individual messages.

avgMessagesPerConversation

integer

Average message count per conversation.

topUsers

array

Top 10 users by message count. Each item has username and messageCount.

dailyActivity

array

Message counts per day for the last 30 days. Each item has date (ISO date) and count.

estimatedTokens

integer

Estimated total token count based on character length (roughly 4 characters per token).

Example

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

{
  "totalConversations": 3241,
  "totalMessages": 18500,
  "avgMessagesPerConversation": 6,
  "topUsers": [
    { "username": "alice", "messageCount": 420 }
  ],
  "dailyActivity": [
    { "date": "2026-03-20", "count": 112 }
  ],
  "estimatedTokens": 240000
}

GET /guilds/:id/conversations/flags

Returns flagged AI messages with an optional status filter. Authentication: API key or JWT Bearer token required.

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.

status

string

Filter by flag status. Options: open, resolved, dismissed.

Response fields

flags

array

List of flag records.

Show Flag object fields

integer

Flag ID.

guildId

string

Discord guild ID.

conversationFirstId

integer

ID of the first message in the flagged conversation.

messageId

integer

ID of the specific flagged message.

flaggedBy

string

User ID or api-secret who created the flag.

reason

string

Reason for flagging.

notes

string | null

Optional additional notes.

status

string

Flag status: open, resolved, or dismissed.

resolvedBy

string | null

User who resolved the flag.

resolvedAt

string | null

ISO 8601 timestamp when resolved.

createdAt

string

ISO 8601 timestamp when the flag was created.

messageContent

string | null

Content of the flagged message.

messageRole

string | null

Role of the flagged message sender.

messageUsername

string | null

Username of the flagged message sender.

total

integer

Total matching flags.

page

integer

Current page.

Example

curl -H "x-api-secret: YOUR_SECRET" \
  "https://volvox.bot/api/v1/guilds/987654321098765432/conversations/flags?status=open"

{
  "flags": [
    {
      "id": 7,
      "guildId": "987654321098765432",
      "conversationFirstId": 10042,
      "messageId": 10045,
      "flaggedBy": "222000222",
      "reason": "Inappropriate content",
      "notes": null,
      "status": "open",
      "resolvedBy": null,
      "resolvedAt": null,
      "createdAt": "2026-03-20T15:00:00.000Z",
      "messageContent": "This is the flagged response...",
      "messageRole": "assistant",
      "messageUsername": "Volvox"
    }
  ],
  "total": 1,
  "page": 1
}

GET /guilds/:id/conversations/:conversationId

Returns all messages in a conversation for replay, including flag status, token estimates, and Discord jump URLs. Authentication: API key or JWT Bearer token required.

Path parameters

string

required

The Discord guild ID.

conversationId

integer

required

The ID of the first message in the conversation.

Response fields

messages

array

Ordered list of messages in the conversation.

Show Message object fields

integer

Message row ID.

role

string

Message role: user or assistant.

content

string

Message text.

username

string

Username of the sender.

createdAt

string

ISO 8601 timestamp.

flagStatus

string | null

Flag status if flagged: open, resolved, or dismissed.

discordMessageId

string | null

Native Discord message ID for jump URLs.

messageUrl

string | null

Full Discord jump URL for the message.

channelId

string

Discord channel ID.

channelName

string | null

Human-readable channel name.

duration

integer

Conversation duration in seconds.

tokenEstimate

integer

Estimated token count for the entire conversation.

Example

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

{
  "messages": [
    {
      "id": 10042,
      "role": "user",
      "content": "How do I deploy to Kubernetes?",
      "username": "alice",
      "createdAt": "2026-03-20T14:00:00.000Z",
      "flagStatus": null,
      "discordMessageId": "1234567890",
      "messageUrl": "https://discord.com/channels/987654321/111222333/1234567890"
    },
    {
      "id": 10043,
      "role": "assistant",
      "content": "To deploy to Kubernetes, you first need...",
      "username": "Volvox",
      "createdAt": "2026-03-20T14:00:05.000Z",
      "flagStatus": null,
      "discordMessageId": "1234567891",
      "messageUrl": "https://discord.com/channels/987654321/111222333/1234567891"
    }
  ],
  "channelId": "111222333",
  "channelName": "ai-chat",
  "duration": 720,
  "tokenEstimate": 512
}

POST /guilds/:id/conversations/:conversationId/flag

Flags a specific AI message in a conversation for moderator review. Authentication: API key or JWT Bearer token required.

Path parameters

string

required

The Discord guild ID.

conversationId

integer

required

The conversation ID (first message ID).

Request body

messageId

integer

required

ID of the specific message to flag.

reason

string

required

Reason for flagging. Maximum 500 characters.

notes

string

Optional additional notes. Maximum 2,000 characters.

Response fields

flagId

integer

ID of the created flag record.

status

string

Always open on creation.

Example

curl -X POST \
  -H "x-api-secret: YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"messageId": 10045, "reason": "Inappropriate content"}' \
  https://volvox.bot/api/v1/guilds/987654321098765432/conversations/10042/flag

{
  "flagId": 7,
  "status": "open"
}

Overview

Endpoints

GET /guilds/:id/conversations

Path parameters

Query parameters

Response fields

Example

GET /guilds/:id/conversations/stats

Path parameters

Response fields

Example

GET /guilds/:id/conversations/flags

Path parameters

Query parameters

Response fields

Example

GET /guilds/:id/conversations/:conversationId

Path parameters

Response fields

Example

POST /guilds/:id/conversations/:conversationId/flag

Path parameters

Request body

Response fields

Example

Build docs developers (and LLMs) love

Overview

Endpoints

​GET /guilds/:id/conversations

​Path parameters

​Query parameters

​Response fields

​Example

​GET /guilds/:id/conversations/stats

​Path parameters

​Response fields

​Example

​GET /guilds/:id/conversations/flags

​Path parameters

​Query parameters

​Response fields

​Example

​GET /guilds/:id/conversations/:conversationId

​Path parameters

​Response fields

​Example

​POST /guilds/:id/conversations/:conversationId/flag

​Path parameters

​Request body

​Response fields

​Example

Build docs developers (and LLMs) love

GET /guilds/:id/conversations

Path parameters

Query parameters

Response fields

Example

GET /guilds/:id/conversations/stats

Path parameters

Response fields

Example

GET /guilds/:id/conversations/flags

Path parameters

Query parameters

Response fields

Example

GET /guilds/:id/conversations/:conversationId

Path parameters

Response fields

Example

POST /guilds/:id/conversations/:conversationId/flag

Path parameters

Request body

Response fields

Example