Moderator Management

The Moderator Management API allows you to create, configure, and monitor automated AI agents that enforce community guidelines across supported platforms (e.g., Discord). These agents evaluate incoming messages, assign severity scores, and queue moderation actions for review or execution.

Moderator Configuration

Every moderator is defined by a conf object. This configuration dictates the AI agent's personality, the rules it must enforce, and the context of the server it is protecting.

Configuration Object Schema

The conf dictionary typically contains:

guidelines: A string detailing the specific rules the AI should look for.
server_summary: Contextual information about the community to help the AI understand the tone of conversations.

Creating a Moderator

To create a new moderator, send a POST request to the /moderators/ endpoint. Note that the number of active moderators is subject to your Pricing Tier limits.

POST /moderators/
Content-Type: application/json

{
  "name": "General Chat Defender",
  "description": "Monitors #general for toxicity and spam.",
  "platform": "discord",
  "platform_server_id": "123456789012345678",
  "conf": {
    "guidelines": "No hate speech, no excessive caps, no self-promotion.",
    "server_summary": "A friendly community for Python developers."
  }
}

Listing and Filtering

You can retrieve a paginated list of all moderators associated with your account. This endpoint supports filtering by platform, status, and name.

Query Parameters:

skip: Number of records to skip (default: 0).
limit: Number of records to return (default: 50, max: 100).
platform: Filter by platform (e.g., discord). Supports CSV format.
status: Filter by status (e.g., online, offline).
name: Case-insensitive search for the moderator name.

GET /moderators/?platform=discord&status=online&limit=10

Monitoring Performance

The API provides dedicated endpoints for tracking how effective a moderator is and identifying problematic users within a community.

Moderator Statistics

The stats endpoint returns aggregate data on how many messages were evaluated and how many actions (kicks, timeouts, replies) were suggested. It includes time-series data suitable for rendering bar charts.

GET /moderators/{moderator_id}/stats

Response Example:

{
  "evaluations_count": 1500,
  "actions_count": 42,
  "bar_chart": [
    {
      "date": "2023-10-27",
      "evaluations_count": 450,
      "actions_count": 12
    }
  ]
}

User Behavior Scores

Gova tracks the "Behavior Score" of individual users on the platform. A lower score typically indicates a history of guideline violations. You can retrieve a list of the most active or problematic users monitored by a specific agent.

GET /moderators/{moderator_id}/behavior-scores

Moderator Lifecycle

A moderator can exist in several states, reflected in the status field:

ONLINE: The moderator is actively listening to events and evaluating messages.
OFFLINE: The moderator is created but is not currently processing events.
PAUSED: The moderator is active but is not suggesting new actions.

Updating Configuration

You can update a moderator's name, description, or AI configuration at any time. Updates to the conf object are propagated to the moderation engine in real-time.

PATCH /moderators/{moderator_id}
Content-Type: application/json

{
  "conf": {
    "guidelines": "Updated guidelines: Now including no-spoiler rules."
  }
}

Endpoint Reference

Schema: ModeratorResponse

API Operations

| Method | Path | Description | | :--- | :--- | :--- | | POST | /moderators/ | Create a new moderator. | | GET | /moderators/ | List moderators with pagination/filtering. | | GET | /moderators/{id} | Get detailed information for one moderator. | | PATCH | /moderators/{id} | Update configuration or metadata. | | DELETE | /moderators/{id} | Remove a moderator. | | GET | /moderators/{id}/stats | Get activity and evaluation metrics. | | GET | /moderators/{id}/behavior-scores | Get top behavior scores by user. |