Skip to content

API Reference

Jump to bottom
pancakes-proxy edited this page Jul 14, 2025 · 1 revision

API Reference

Complete reference for AIMod's REST API endpoints, WebSocket connections, and integration capabilities.

🌐 Base Information

API Base URL

Production: https://yourdomain.com/api
Development: http://localhost:8000/api

Authentication

All API endpoints require authentication via JWT tokens obtained through Discord OAuth2.

Authorization: Bearer <jwt_token>

Response Format

All responses follow a consistent JSON format:

{
  "success": true,
  "data": { ... },
  "message": "Operation completed successfully",
  "timestamp": "2025-01-13T10:30:00Z"
}

Error responses:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input parameters",
    "details": { ... }
  },
  "timestamp": "2025-01-13T10:30:00Z"
}

🔐 Authentication Endpoints

Login

Initiate Discord OAuth2 authentication flow.

GET /auth/login

Response:

302 Redirect to Discord OAuth2 authorization URL

Callback

Handle Discord OAuth2 callback and issue JWT token.

GET /auth/callback?code={authorization_code}

Parameters:

  • code (string): Authorization code from Discord

Response:

{
  "success": true,
  "data": {
    "user": {
      "id": "123456789",
      "username": "user#1234",
      "avatar": "avatar_hash"
    },
    "token": "jwt_token_here"
  }
}

Logout

Invalidate current session.

POST /auth/logout

Response:

{
  "success": true,
  "message": "Logged out successfully"
}

🏰 Guild Endpoints

Get User Guilds

Retrieve guilds where the user has administrative permissions.

GET /guilds

Response:

{
  "success": true,
  "data": [
    {
      "id": "987654321",
      "name": "My Discord Server",
      "icon": "guild_icon_hash",
      "owner": false,
      "permissions": 8
    }
  ]
}

Get Guild Configuration

Retrieve comprehensive guild configuration.

GET /guilds/{guild_id}/config

Parameters:

  • guild_id (string): Discord guild ID

Response:

{
  "success": true,
  "data": {
    "general": {
      "enabled": true,
      "prefix": "!",
      "ai_model": "github_copilot/gpt-4.1"
    },
    "moderation": {
      "confidence_threshold": 70,
      "auto_timeout_enabled": true,
      "timeout_duration": 3600
    },
    "security": {
      "botdetect": {
        "enabled": false,
        "keywords": ["spam", "scam"],
        "action": "timeout"
      }
    }
  }
}

Update Guild Configuration

Update guild configuration settings.

PUT /guilds/{guild_id}/config

Request Body:

{
  "general": {
    "enabled": true,
    "ai_model": "openai/gpt-4"
  },
  "moderation": {
    "confidence_threshold": 80
  }
}

Response:

{
  "success": true,
  "message": "Configuration updated successfully",
  "data": {
    "updated_fields": ["general.ai_model", "moderation.confidence_threshold"]
  }
}

📊 Analytics Endpoints

Guild Statistics

Get comprehensive guild statistics.

GET /guilds/{guild_id}/stats?timeframe={timeframe}

Parameters:

  • guild_id (string): Discord guild ID
  • timeframe (string): Time period (1h, 6h, 24h, 7d, 30d)

Response:

{
  "success": true,
  "data": {
    "timeframe": "24h",
    "message_count": 1250,
    "member_joins": 15,
    "member_leaves": 3,
    "moderation_actions": 8,
    "activity_score": 85.2
  }
}

Command Analytics

Get command usage analytics.

GET /guilds/{guild_id}/analytics/commands?days={days}

Parameters:

  • guild_id (string): Discord guild ID
  • days (integer): Number of days to analyze (default: 30)

Response:

{
  "success": true,
  "data": {
    "total_commands": 456,
    "unique_commands": 23,
    "top_commands": [
      {
        "command": "config",
        "usage_count": 89,
        "unique_users": 12,
        "last_used": "2025-01-13T09:15:00Z"
      }
    ],
    "daily_usage": [
      {
        "date": "2025-01-13",
        "count": 45
      }
    ]
  }
}

Moderation Analytics

Get moderation action analytics.

GET /guilds/{guild_id}/analytics/moderation?days={days}

Response:

{
  "success": true,
  "data": {
    "total_actions": 156,
    "action_distribution": [
      {
        "action": "TIMEOUT",
        "count": 89,
        "percentage": 57.1
      },
      {
        "action": "WARN",
        "count": 45,
        "percentage": 28.8
      }
    ],
    "ai_vs_human": [
      {
        "type": "AI",
        "count": 134
      },
      {
        "type": "Human",
        "count": 22
      }
    ]
  }
}

👤 User Endpoints

User Profile

Get detailed user profile information.

GET /users/{user_id}/profile?guild_id={guild_id}

Parameters:

  • user_id (string): Discord user ID
  • guild_id (string, optional): Specific guild context

Response:

{
  "success": true,
  "data": {
    "user_id": "123456789",
    "username": "user#1234",
    "avatar_url": "https://cdn.discordapp.com/avatars/...",
    "total_infractions": 3,
    "recent_infractions": [
      {
        "timestamp": "2025-01-12T14:30:00Z",
        "rule": "Rule 1",
        "action": "TIMEOUT",
        "reason": "Spam messages"
      }
    ],
    "join_date": "2024-06-15T10:00:00Z",
    "last_seen": "2025-01-13T09:45:00Z"
  }
}

User Infractions

Get user's infraction history.

GET /guilds/{guild_id}/users/{user_id}/infractions?limit={limit}&offset={offset}

Parameters:

  • guild_id (string): Discord guild ID
  • user_id (string): Discord user ID
  • limit (integer): Number of records to return (default: 50)
  • offset (integer): Number of records to skip (default: 0)

Response:

{
  "success": true,
  "data": {
    "infractions": [
      {
        "id": 123,
        "timestamp": "2025-01-12T14:30:00Z",
        "rule_violated": "Rule 1",
        "action_taken": "TIMEOUT",
        "reasoning": "Spam messages detected by AI",
        "moderator": "AI System"
      }
    ],
    "total_count": 3,
    "has_more": false
  }
}

🛠️ Moderation Endpoints

Create Moderation Action

Execute a moderation action against a user.

POST /guilds/{guild_id}/moderation/action

Request Body:

{
  "target_user_id": 123456789,
  "action_type": "TIMEOUT",
  "reason": "Violation of server rules",
  "duration_seconds": 3600
}

Response:

{
  "success": true,
  "data": {
    "action_id": 456,
    "executed_at": "2025-01-13T10:30:00Z",
    "status": "completed"
  }
}

Appeal Management

Handle user appeals for moderation actions.

GET /guilds/{guild_id}/appeals?status={status}
POST /guilds/{guild_id}/appeals/{appeal_id}/respond

🔧 Configuration Endpoints

Bot Detection Settings

Configure bot detection parameters.

GET /guilds/{guild_id}/config/botdetect
PUT /guilds/{guild_id}/config/botdetect

Request Body (PUT):

{
  "enabled": true,
  "keywords": ["discord.gg/", "free nitro"],
  "action": "timeout",
  "timeout_duration": 3600,
  "whitelist_roles": ["123456789"],
  "whitelist_users": ["987654321"]
}

Raid Defense Settings

Configure raid defense parameters.

GET /guilds/{guild_id}/config/raiddefense
PUT /guilds/{guild_id}/config/raiddefense

Logging Settings

Configure event logging.

GET /guilds/{guild_id}/config/logging
PUT /guilds/{guild_id}/config/logging

📡 WebSocket Events

Real-time Updates

Connect to WebSocket for real-time updates.

const ws = new WebSocket('wss://yourdomain.com/ws/guilds/123456789');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received update:', data);
};

Event Types

  • moderation_action: New moderation action taken
  • config_update: Configuration changed
  • member_join: New member joined
  • member_leave: Member left server
  • security_alert: Security event detected

🚨 Error Codes

HTTP Status Codes

  • 200: Success
  • 201: Created
  • 400: Bad Request
  • 401: Unauthorized
  • 403: Forbidden
  • 404: Not Found
  • 429: Rate Limited
  • 500: Internal Server Error

Application Error Codes

  • VALIDATION_ERROR: Invalid input parameters
  • PERMISSION_DENIED: Insufficient permissions
  • RESOURCE_NOT_FOUND: Requested resource not found
  • RATE_LIMIT_EXCEEDED: API rate limit exceeded
  • CONFIGURATION_ERROR: Invalid configuration
  • AI_SERVICE_ERROR: AI provider service error
  • DATABASE_ERROR: Database operation failed

📝 Rate Limiting

Limits

  • General API: 100 requests per minute per user
  • Authentication: 10 requests per minute per IP
  • Analytics: 30 requests per minute per user
  • Configuration: 20 requests per minute per user

Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642089600

🔌 Webhooks

Webhook Configuration

Configure webhooks for external integrations.

POST /guilds/{guild_id}/webhooks

Request Body:

{
  "url": "https://your-service.com/webhook",
  "events": ["moderation_action", "security_alert"],
  "secret": "webhook_secret_key"
}

Webhook Payload

{
  "event_type": "moderation_action",
  "guild_id": "987654321",
  "timestamp": "2025-01-13T10:30:00Z",
  "data": {
    "action": "TIMEOUT",
    "user_id": "123456789",
    "reason": "Spam detected",
    "moderator": "AI System"
  },
  "signature": "sha256=..."
}

For more detailed examples and integration guides, see the Developer Guide.

Clone this wiki locally