API Documentation

Complete reference for all API endpoints in the DBK Gaming Web Panel.

Base URL

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

Authentication

Most endpoints require authentication via session cookies. The session cookie is set automatically after logging in via Discord OAuth2.

Authentication Flow

Login: Redirect user to /api/auth/login
Callback: Discord redirects to /api/auth/callback with authorization code
Session: Server creates session and sets httpOnly cookie
Authenticated Requests: Include session cookie in all subsequent requests

Session Cookie

Name: connect.sid
HttpOnly: Yes
Secure: Yes (in production)
SameSite: Lax

Rate Limiting

Authentication endpoints: 10 requests per 15 minutes per IP
API endpoints: 60 requests per 15 minutes per IP

Response Format

All responses follow this format:

{
  "success": true,
  "data": { ... }
}

Error responses:

{
  "success": false,
  "error": "Error message",
  "code": "ERROR_CODE"
}

Common HTTP Status Codes

200 OK: Request successful
201 Created: Resource created
400 Bad Request: Invalid input
401 Unauthorized: Not authenticated
403 Forbidden: Not authorized
404 Not Found: Resource not found
429 Too Many Requests: Rate limit exceeded
500 Internal Server Error: Server error

Authentication Endpoints
User Endpoints
Server Endpoints
Admin Endpoints
Live Chat Endpoints
Notification Endpoints

Authentication Endpoints

Login with Discord

Endpoint: GET /api/auth/login

Redirects to Discord OAuth2 authorization page.

Response: Redirect to Discord

OAuth Callback

Endpoint: GET /api/auth/callback

Handles Discord OAuth2 callback and creates session.

Query Parameters:

code (string): Authorization code from Discord

Response: Redirect to frontend with session cookie

Get Current User

Endpoint: GET /api/auth/me

Returns the currently authenticated user.

Authentication: Required

Response:

{
  "success": true,
  "data": {
    "id": "123456789012345678",
    "username": "PlayerOne",
    "discriminator": "0001",
    "avatar": "avatar_hash",
    "bio": "Gamer and streamer",
    "favoriteGames": "Valorant,League of Legends",
    "socialLinks": "{\"twitter\":\"@player\",\"twitch\":\"player\"}",
    "role": "MEMBER",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}

Logout

Endpoint: POST /api/auth/logout

Destroys the current session.

Authentication: Required

Response:

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

User Endpoints

List Users (Admin Only)

Endpoint: GET /api/users

Returns paginated list of all users.

Authentication: Required (Admin)

Query Parameters:

limit (number, optional): Results per page (default: 20, max: 100)
offset (number, optional): Number of results to skip (default: 0)
search (string, optional): Search by username

Response:

{
  "success": true,
  "data": {
    "users": [...],
    "total": 150,
    "limit": 20,
    "offset": 0
  }
}

Get User by ID

Endpoint: GET /api/users/:id

Returns a specific user by Discord ID.

Authentication: Required (Admin or self)

Response:

{
  "success": true,
  "data": {
    "id": "123456789012345678",
    "username": "PlayerOne",
    ...
  }
}

Update User

Endpoint: PATCH /api/users/:id

Updates user profile information.

Authentication: Required (Admin or self)

Request Body:

{
  "bio": "Updated bio text (max 500 chars)",
  "favoriteGames": "Game1,Game2,Game3",
  "socialLinks": {
    "twitter": "@username",
    "twitch": "username",
    "youtube": "channelname",
    "steam": "steamid"
  }
}

Response:

{
  "success": true,
  "data": {
    "id": "123456789012345678",
    "username": "PlayerOne",
    "bio": "Updated bio text",
    ...
  }
}

Delete User (Admin Only)

Endpoint: DELETE /api/users/:id

Deletes a user account.

Authentication: Required (Admin)

Response:

{
  "success": true,
  "message": "User deleted successfully"
}

Members Endpoints

Public endpoints for browsing community members.

List Members

Endpoint: GET /api/members

Returns paginated list of members (public profiles).

Authentication: Not required

Query Parameters:

limit (number, optional): Results per page (default: 20, max: 100)
offset (number, optional): Number of results to skip (default: 0)
search (string, optional): Search by username
role (string, optional): Filter by role (MEMBER, ADMIN)
sortBy (string, optional): Sort field (username, createdAt, default: createdAt)
sortOrder (string, optional): Sort order (asc, desc, default: desc)

Response:

{
  "success": true,
  "data": {
    "members": [...],
    "total": 150,
    "limit": 20,
    "offset": 0
  }
}

Get Member by ID

Endpoint: GET /api/members/:id

Returns public profile of a member.

Authentication: Not required

Response:

{
  "success": true,
  "data": {
    "id": "123456789012345678",
    "username": "PlayerOne",
    "avatar": "avatar_hash",
    "bio": "Gamer and streamer",
    "favoriteGames": "Valorant,League of Legends",
    "socialLinks": {...},
    "role": "MEMBER",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}

Server Endpoints

List Servers

Endpoint: GET /api/servers

Returns paginated list of game servers.

Authentication: Not required

Query Parameters:

limit (number, optional): Results per page (default: 20, max: 100)
offset (number, optional): Number of results to skip (default: 0)
search (string, optional): Search by server name/description
gameType (string, optional): Filter by game type
region (string, optional): Filter by region
isOfficial (boolean, optional): Filter official servers
isFeatured (boolean, optional): Filter featured servers
sortBy (string, optional): Sort field (createdAt, name, default: createdAt)
sortOrder (string, optional): Sort order (asc, desc, default: desc)

Response:

{
  "success": true,
  "data": {
    "servers": [...],
    "total": 50,
    "limit": 20,
    "offset": 0
  }
}

Get Server by ID

Endpoint: GET /api/servers/:id

Returns detailed information about a server including games.

Authentication: Not required

Response:

{
  "success": true,
  "data": {
    "id": "123456789012345678",
    "description": "Official DBK Gaming server",
    "region": "EU",
    "isOfficial": true,
    "isFeatured": true,
    "games": [
      {
        "id": "game_id_1",
        "name": "Valorant",
        "emoji": "🎮",
        "setupMode": "advanced"
      }
    ],
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}

Add Server

Endpoint: POST /api/servers

Adds a new server listing.

Authentication: Required

Request Body:

{
  "guildId": "123456789012345678",
  "description": "Amazing gaming community",
  "region": "NA"
}

Response:

{
  "success": true,
  "data": {
    "id": "123456789012345678",
    "description": "Amazing gaming community",
    "region": "NA",
    "isApproved": true,
    "addedBy": "user_id"
  }
}

Update Server

Endpoint: PATCH /api/servers/:id

Updates server information.

Authentication: Required (Server owner or Admin)

Request Body:

{
  "description": "Updated description",
  "region": "EU"
}

Response:

{
  "success": true,
  "data": {
    "id": "123456789012345678",
    "description": "Updated description",
    ...
  }
}

Delete Server

Endpoint: DELETE /api/servers/:id

Removes a server listing.

Authentication: Required (Server owner or Admin)

Response:

{
  "success": true,
  "message": "Server deleted successfully"
}

Game Endpoints

List Games for Server

Endpoint: GET /api/servers/:serverId/games

Returns all games for a specific server.

Authentication: Not required

Response:

{
  "success": true,
  "data": {
    "games": [
      {
        "id": "game_id_1",
        "name": "Valorant",
        "emoji": "🎮",
        "setupMode": "advanced",
        "archived": false,
        "createdAt": "2024-01-01T00:00:00.000Z"
      }
    ]
  }
}

Add Game to Server

Endpoint: POST /api/servers/:serverId/games

Adds a new game to a server. Creates a pending record that the bot will process.

Authentication: Required (Server owner or Admin)

Request Body:

{
  "name": "Valorant",
  "emoji": "🎮",
  "setupMode": "advanced",
  "enablePlus": true,
  "voiceChannels": 2
}

Response:

{
  "success": true,
  "data": {
    "id": "game_id",
    "name": "Valorant",
    "status": "pending"
  }
}

Delete Game from Server

Endpoint: DELETE /api/servers/:serverId/games/:gameId

Removes a game from a server (archives it).

Authentication: Required (Server owner or Admin)

Response:

{
  "success": true,
  "message": "Game archived successfully"
}

Announcement Endpoints

List Announcements

Endpoint: GET /api/announcements

Returns published announcements (all announcements if admin).

Authentication: Not required (Admin to see drafts)

Query Parameters:

limit (number, optional): Results per page (default: 10, max: 50)
offset (number, optional): Number of results to skip (default: 0)

Response:

{
  "success": true,
  "data": {
    "announcements": [
      {
        "id": "announcement_id",
        "title": "Welcome to DBK Gaming!",
        "body": "We're excited to have you...",
        "author": {
          "id": "user_id",
          "username": "Admin"
        },
        "published": true,
        "createdAt": "2024-01-01T00:00:00.000Z"
      }
    ],
    "total": 5
  }
}

Create Announcement (Admin Only)

Endpoint: POST /api/announcements

Creates a new announcement.

Authentication: Required (Admin)

Request Body:

{
  "title": "New Feature Release",
  "body": "We've added exciting new features...",
  "published": true
}

Response:

{
  "success": true,
  "data": {
    "id": "announcement_id",
    "title": "New Feature Release",
    ...
  }
}

Update Announcement (Admin Only)

Endpoint: PATCH /api/announcements/:id

Updates an announcement.

Authentication: Required (Admin)

Request Body:

{
  "title": "Updated Title",
  "body": "Updated content",
  "published": true
}

Response:

{
  "success": true,
  "data": {
    "id": "announcement_id",
    "title": "Updated Title",
    ...
  }
}

Delete Announcement (Admin Only)

Endpoint: DELETE /api/announcements/:id

Deletes an announcement.

Authentication: Required (Admin)

Response:

{
  "success": true,
  "message": "Announcement deleted successfully"
}

Admin Endpoints

Get Dashboard Statistics (Admin Only)

Endpoint: GET /api/admin/stats

Returns platform statistics for admin dashboard.

Authentication: Required (Admin)

Response:

{
  "success": true,
  "data": {
    "totalUsers": 1234,
    "totalServers": 56,
    "totalGames": 178,
    "activeSessions": 45,
    "officialServers": 5,
    "pendingApprovals": 3
  }
}

Get Audit Logs (Admin Only)

Endpoint: GET /api/admin/audit-logs

Returns admin action audit trail.

Authentication: Required (Admin)

Query Parameters:

limit (number, optional): Results per page (default: 50, max: 200)
offset (number, optional): Number of results to skip (default: 0)

Response:

{
  "success": true,
  "data": {
    "logs": [
      {
        "id": "log_id",
        "adminId": "admin_user_id",
        "action": "UPDATE_USER_ROLE",
        "targetType": "USER",
        "targetId": "target_user_id",
        "metadata": "{\"oldRole\":\"MEMBER\",\"newRole\":\"ADMIN\"}",
        "createdAt": "2024-01-01T00:00:00.000Z"
      }
    ],
    "total": 250
  }
}

Update User Role (Admin Only)

Endpoint: PATCH /api/admin/users/:id/role

Changes a user's role.

Authentication: Required (Admin)

Request Body:

{
  "role": "ADMIN"
}

Response:

{
  "success": true,
  "data": {
    "id": "user_id",
    "username": "PlayerOne",
    "role": "ADMIN"
  }
}

Feature/Unfeature Server (Admin Only)

Endpoint: PATCH /api/admin/servers/:id/feature

Toggles featured status for a server.

Authentication: Required (Admin)

Request Body:

{
  "isFeatured": true
}

Response:

{
  "success": true,
  "data": {
    "id": "server_id",
    "isFeatured": true
  }
}

Get LiveChat Settings (Admin Only)

Endpoint: GET /api/admin/livechat-settings

Returns livechat Discord integration settings.

Authentication: Required (MANAGE_LIVECHAT_SETTINGS or MANAGE_SYSTEM permission)

Response:

{
  "id": "singleton",
  "enabled": true,
  "webhookUrl": "https://discord.com/api/webhooks/...",
  "guildId": "123456789012345678",
  "channelId": "987654321098765432",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

Update LiveChat Settings (Admin Only)

Endpoint: PATCH /api/admin/livechat-settings

Updates livechat Discord integration settings.

Authentication: Required (MANAGE_LIVECHAT_SETTINGS or MANAGE_SYSTEM permission)

Request Body:

{
  "enabled": true,
  "webhookUrl": "https://discord.com/api/webhooks/...",
  "guildId": "123456789012345678",
  "channelId": "987654321098765432"
}

Response:

{
  "id": "singleton",
  "enabled": true,
  "webhookUrl": "https://discord.com/api/webhooks/...",
  "guildId": "123456789012345678",
  "channelId": "987654321098765432",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

Test LiveChat Webhook (Admin Only)

Endpoint: POST /api/admin/livechat-settings/test

Tests the Discord webhook connection by sending a test message.

Authentication: Required (MANAGE_LIVECHAT_SETTINGS or MANAGE_SYSTEM permission)

Request Body:

{
  "webhookUrl": "https://discord.com/api/webhooks/..."
}

Response:

{
  "success": true,
  "message": "Test webhook sent successfully"
}

Error Response:

{
  "error": "Failed to send test webhook",
  "details": "Webhook URL is invalid or unreachable"
}

Notification Endpoints

List User Notifications

Endpoint: GET /api/notifications

Returns notifications for the authenticated user.

Authentication: Required

Query Parameters:

limit (number, optional): Results per page (default: 20, max: 100)
offset (number, optional): Number of results to skip (default: 0)
unreadOnly (boolean, optional): Only show unread notifications

Response:

{
  "success": true,
  "data": {
    "notifications": [
      {
        "id": "notification_id",
        "type": "SERVER_APPROVED",
        "title": "Server Approved",
        "body": "Your server has been approved!",
        "read": false,
        "createdAt": "2024-01-01T00:00:00.000Z"
      }
    ],
    "unreadCount": 5
  }
}

Mark Notification as Read

Endpoint: PATCH /api/notifications/:id/read

Marks a notification as read.

Authentication: Required

Response:

{
  "success": true,
  "data": {
    "id": "notification_id",
    "read": true
  }
}

Delete Notification

Endpoint: DELETE /api/notifications/:id

Deletes a notification.

Authentication: Required

Response:

{
  "success": true,
  "message": "Notification deleted successfully"
}

Search Endpoint

Global Search

Endpoint: GET /api/search

Searches across members and servers.

Authentication: Not required

Query Parameters:

q (string, required): Search query
type (string, optional): Search type (members, servers, all, default: all)
limit (number, optional): Results per type (default: 10, max: 50)

Response:

{
  "success": true,
  "data": {
    "members": [...],
    "servers": [...],
    "total": 15
  }
}

AMP Server Endpoints

List AMP Servers

Endpoint: GET /api/amp-servers

Returns paginated list of official AMP-managed servers.

Authentication: Not required

Query Parameters:

limit (number, optional): Results per page (default: 20, max: 100)
offset (number, optional): Number of results to skip (default: 0)
gameType (string, optional): Filter by game type
search (string, optional): Search by server name
isRunning (boolean, optional): Filter by running status

Response:

{
  "success": true,
  "data": {
    "servers": [
      {
        "id": "amp_server_id",
        "ampInstanceId": "instance_123",
        "instanceName": "Official Minecraft Server",
        "gameType": "minecraft",
        "ip": "192.168.1.100",
        "port": 25565,
        "isRunning": true,
        "playerCount": 15,
        "maxPlayers": 20,
        "uptime": 86400,
        "lastSync": "2024-01-01T00:00:00.000Z"
      }
    ],
    "total": 10,
    "limit": 20,
    "offset": 0
  }
}

Get AMP Server by ID

Endpoint: GET /api/amp-servers/:id

Returns detailed information about a specific AMP server.

Authentication: Not required

Response:

{
  "success": true,
  "data": {
    "id": "amp_server_id",
    "ampInstanceId": "instance_123",
    "instanceName": "Official Minecraft Server",
    "gameType": "minecraft",
    "ip": "192.168.1.100",
    "port": 25565,
    "isRunning": true,
    "playerCount": 15,
    "maxPlayers": 20,
    "uptime": 86400,
    "lastSync": "2024-01-01T00:00:00.000Z",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
}

Start AMP Server (Admin Only)

Endpoint: POST /api/amp-servers/:id/start

Starts an AMP-managed server instance.

Authentication: Required (Admin)

Response:

{
  "success": true,
  "message": "Server start command sent successfully"
}

Stop AMP Server (Admin Only)

Endpoint: POST /api/amp-servers/:id/stop

Stops an AMP-managed server instance.

Authentication: Required (Admin)

Response:

{
  "success": true,
  "message": "Server stop command sent successfully"
}

Force Sync AMP Servers (Admin Only)

Endpoint: POST /api/amp-servers/sync

Forces immediate synchronization with AMP API to update server status.

Authentication: Required (Admin)

Response:

{
  "success": true,
  "data": {
    "synced": 10,
    "updated": 8,
    "errors": 0
  }
}

Documentation Endpoints

List Documentation Files

Endpoint: GET /api/docs

Returns list of available documentation files with metadata.

Authentication: Not required

Response:

{
  "success": true,
  "data": {
    "docs": [
      {
        "slug": "setup",
        "title": "Setup Guide",
        "category": "Getting Started",
        "description": "Complete installation and configuration guide"
      },
      {
        "slug": "api",
        "title": "API Documentation",
        "category": "Development",
        "description": "Complete API reference for all endpoints"
      }
    ]
  }
}

Get Documentation Content

Endpoint: GET /api/docs/:slug

Returns markdown content for a specific documentation file.

Authentication: Not required

Response:

{
  "success": true,
  "data": {
    "slug": "setup",
    "title": "Setup Guide",
    "category": "Getting Started",
    "content": "# Setup Guide\n\n..."
  }
}

Rank Management Endpoints

List Users with Ranks (Admin Only)

Endpoint: GET /api/ranks/users

Returns paginated list of users with their ranks and permissions.

Authentication: Required (Admin)

Query Parameters:

page (number, optional): Page number (default: 1)
limit (number, optional): Results per page (default: 20, max: 100)
search (string, optional): Search by username
rank (string, optional): Filter by rank (MEMBER, MODERATOR, ADMIN)

Response:

{
  "users": [
    {
      "id": "123456789012345678",
      "username": "PlayerOne",
      "avatar": "avatar_hash",
      "role": "MEMBER",
      "rank": {
        "id": "rank_id",
        "rank": "MODERATOR",
        "level": 50,
        "grantedBy": "admin_id",
        "grantedAt": "2024-01-01T00:00:00.000Z"
      },
      "permissions": [...]
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}

Update User Rank (Admin Only)

Endpoint: PATCH /api/ranks/users/:id

Changes a user's rank in the platform hierarchy.

Authentication: Required (Admin)

Request Body:

{
  "rank": "MODERATOR"
}

Response:

{
  "id": "user_id",
  "username": "PlayerOne",
  "rank": {
    "rank": "MODERATOR",
    "level": 50,
    "grantedBy": "admin_id",
    "grantedAt": "2024-01-01T00:00:00.000Z"
  },
  "permissions": [...]
}

Notes:

Cannot change your own rank
Cannot promote users to your rank or higher
Cannot modify users at or above your level

List Available Permissions (Admin Only)

Endpoint: GET /api/ranks/permissions

Returns list of all available permissions.

Authentication: Required (Admin)

Response:

{
  "permissions": [
    {
      "key": "MANAGE_USERS",
      "value": "manage_users",
      "description": "Manage user accounts and roles"
    },
    {
      "key": "MODERATE_FORUM",
      "value": "moderate_forum",
      "description": "Moderate forum content"
    }
  ]
}

Grant Permission (Admin Only)

Endpoint: POST /api/ranks/permissions

Grants or revokes a specific permission for a user.

Authentication: Required (Admin)

Request Body:

{
  "userId": "user_id",
  "permission": "moderate_forum",
  "granted": true,
  "scope": "category_id"
}

Response:

{
  "id": "permission_id",
  "userId": "user_id",
  "permission": "moderate_forum",
  "granted": true,
  "scope": "category_id",
  "grantedBy": "admin_id",
  "createdAt": "2024-01-01T00:00:00.000Z"
}

Notes:

scope is optional (for category-specific or server-specific permissions)
Cannot grant permissions to users at or above your level

Revoke Permission (Admin Only)

Endpoint: DELETE /api/ranks/permissions/:id

Revokes a specific permission from a user.

Authentication: Required (Admin)

Response:

{
  "success": true,
  "message": "Permission revoked"
}

Server Member Endpoints

List Server Members

Endpoint: GET /api/servers/:id/members

Returns paginated list of members for a server.

Authentication: Required (Server member or Admin)

Query Parameters:

page (number, optional): Page number (default: 1)
limit (number, optional): Results per page (default: 20, max: 100)

Response:

{
  "members": [
    {
      "id": "member_id",
      "serverId": "server_id",
      "userId": "user_id",
      "rank": "SERVER_ADMIN",
      "joinedAt": "2024-01-01T00:00:00.000Z",
      "user": {
        "id": "user_id",
        "username": "PlayerOne",
        "avatar": "avatar_hash"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 50,
    "pages": 3
  }
}

Add Server Member

Endpoint: POST /api/servers/:id/members

Adds a new member to a server.

Authentication: Required (Server Admin or higher)

Request Body:

{
  "userId": "user_id",
  "rank": "SERVER_MEMBER"
}

Response:

{
  "id": "member_id",
  "serverId": "server_id",
  "userId": "user_id",
  "rank": "SERVER_MEMBER",
  "joinedAt": "2024-01-01T00:00:00.000Z",
  "user": {
    "id": "user_id",
    "username": "PlayerOne",
    "avatar": "avatar_hash"
  }
}

Update Server Member Rank

Endpoint: PATCH /api/servers/:id/members/:userId

Updates a member's rank within a server.

Authentication: Required (Server Owner or Admin)

Request Body:

{
  "rank": "SERVER_ADMIN"
}

Response:

{
  "id": "member_id",
  "serverId": "server_id",
  "userId": "user_id",
  "rank": "SERVER_ADMIN",
  "user": {...}
}

Remove Server Member

Endpoint: DELETE /api/servers/:id/members/:userId

Removes a member from a server.

Authentication: Required (Server Owner or Admin, or self)

Response:

{
  "message": "Member removed successfully"
}

Forum Endpoints

List Forum Categories

Endpoint: GET /api/forum/categories

Returns all forum categories with permissions filtering.

Authentication: Not required

Response:

{
  "categories": [
    {
      "id": "category_id",
      "name": "General Discussion",
      "slug": "general",
      "description": "Talk about anything",
      "icon": "💬",
      "position": 0,
      "minReadRank": "MEMBER",
      "minWriteRank": "MEMBER",
      "_count": {
        "threads": 150
      },
      "threads": [...]
    }
  ]
}

Get Forum Category

Endpoint: GET /api/forum/categories/:slug

Returns detailed information about a specific category.

Authentication: Not required

Response:

{
  "category": {
    "id": "category_id",
    "name": "General Discussion",
    "slug": "general",
    "description": "Talk about anything",
    "icon": "💬",
    "_count": {
      "threads": 150
    }
  }
}

Create Forum Category (Moderator Only)

Endpoint: POST /api/forum/categories

Creates a new forum category.

Authentication: Required (Moderator)

Request Body:

{
  "name": "New Category",
  "slug": "new-category",
  "description": "Category description",
  "icon": "📚",
  "position": 5,
  "minReadRank": "MEMBER",
  "minWriteRank": "MEMBER"
}

Response:

{
  "id": "category_id",
  "name": "New Category",
  "slug": "new-category",
  ...
}

Update Forum Category (Moderator Only)

Endpoint: PATCH /api/forum/categories/:slug

Updates an existing forum category.

Authentication: Required (Moderator)

Request Body:

{
  "name": "Updated Name",
  "description": "Updated description",
  "position": 3
}

Delete Forum Category (Admin Only)

Endpoint: DELETE /api/forum/categories/:slug

Deletes a forum category and all its threads.

Authentication: Required (Admin)

Response:

{
  "message": "Category deleted successfully"
}

List Forum Threads

Endpoint: GET /api/forum/categories/:slug/threads

Returns paginated threads in a category.

Authentication: Not required

Query Parameters:

page (number, optional): Page number (default: 1)
limit (number, optional): Results per page (default: 20, max: 100)

Response:

{
  "threads": [
    {
      "id": "thread_id",
      "title": "Welcome to the forum!",
      "slug": "welcome",
      "isPinned": true,
      "isLocked": false,
      "viewCount": 1234,
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-05T00:00:00.000Z",
      "author": {
        "id": "user_id",
        "username": "Admin",
        "avatar": "avatar_hash"
      },
      "_count": {
        "posts": 45
      }
    }
  ],
  "pagination": {...}
}

Get Forum Thread

Endpoint: GET /api/forum/categories/:slug/:threadSlug

Returns detailed thread information with posts.

Authentication: Not required

Query Parameters:

page (number, optional): Page number for posts (default: 1)
limit (number, optional): Posts per page (default: 20, max: 100)

Response:

{
  "thread": {
    "id": "thread_id",
    "title": "Welcome to the forum!",
    "content": "First post content (Markdown)",
    "isPinned": true,
    "isLocked": false,
    "viewCount": 1234,
    "author": {...},
    "posts": [...]
  },
  "pagination": {...}
}

Create Forum Thread

Endpoint: POST /api/forum/categories/:slug/threads

Creates a new discussion thread.

Authentication: Required

Request Body:

{
  "title": "My New Thread",
  "content": "Thread content in Markdown format"
}

Response:

{
  "id": "thread_id",
  "title": "My New Thread",
  "slug": "my-new-thread",
  "content": "Thread content...",
  "author": {...}
}

Update Forum Thread

Endpoint: PATCH /api/forum/categories/:slug/:threadSlug

Updates a thread (author or moderator only).

Authentication: Required (Author or Moderator)

Request Body:

{
  "title": "Updated Title",
  "content": "Updated content"
}

Delete Forum Thread

Endpoint: DELETE /api/forum/categories/:slug/:threadSlug

Deletes a thread (author or moderator only).

Authentication: Required (Author or Moderator)

Response:

{
  "message": "Thread deleted successfully"
}

Pin/Unpin Thread (Moderator Only)

Endpoint: PATCH /api/forum/threads/:id/pin

Pins or unpins a thread.

Authentication: Required (Moderator)

Request Body:

{
  "isPinned": true
}

Lock/Unlock Thread (Moderator Only)

Endpoint: PATCH /api/forum/threads/:id/lock

Locks or unlocks a thread.

Authentication: Required (Moderator)

Request Body:

{
  "isLocked": true
}

Create Forum Post

Endpoint: POST /api/forum/threads/:id/posts

Creates a reply to a thread.

Authentication: Required

Request Body:

{
  "content": "Post content in Markdown"
}

Response:

{
  "id": "post_id",
  "threadId": "thread_id",
  "content": "Post content...",
  "author": {...},
  "createdAt": "2024-01-01T00:00:00.000Z"
}

Update Forum Post

Endpoint: PATCH /api/forum/posts/:id

Updates a post (author only).

Authentication: Required (Author)

Request Body:

{
  "content": "Updated post content"
}

Delete Forum Post

Endpoint: DELETE /api/forum/posts/:id

Deletes a post (author or moderator).

Authentication: Required (Author or Moderator)

Response:

{
  "message": "Post deleted successfully"
}

Add Post Reaction

Endpoint: POST /api/forum/posts/:id/reactions

Adds an emoji reaction to a post.

Authentication: Required

Request Body:

{
  "emoji": "👍"
}

Response:

{
  "id": "reaction_id",
  "postId": "post_id",
  "emoji": "👍",
  "user": {...}
}

Remove Post Reaction

Endpoint: DELETE /api/forum/posts/:id/reactions/:reactionId

Removes a reaction from a post.

Authentication: Required (Own reaction only)

Search Forum

Endpoint: GET /api/forum/search

Searches threads and posts.

Authentication: Not required

Query Parameters:

q (string, required): Search query
limit (number, optional): Results limit (default: 20, max: 50)

Response:

{
  "results": {
    "threads": [...],
    "posts": [...]
  }
}

Game Server Endpoints

List Game Servers

Endpoint: GET /api/game-servers

Returns paginated list of approved game servers.

Authentication: Not required

Query Parameters:

page (number, optional): Page number (default: 1)
limit (number, optional): Results per page (default: 20, max: 100)
gameType (string, optional): Filter by game type (minecraft, csgo, rust, etc.)
search (string, optional): Search by name/description/tags
sortBy (string, optional): Sort field (createdAt, name, playerCount, default: createdAt)
sortOrder (string, optional): Sort order (asc, desc, default: desc)

Response:

{
  "servers": [
    {
      "id": "server_id",
      "name": "Awesome Minecraft Server",
      "gameType": "minecraft",
      "ip": "play.example.com",
      "port": 25565,
      "description": "Best survival server!",
      "website": "https://example.com",
      "tags": "survival,economy,pvp",
      "isApproved": true,
      "isActive": true,
      "submitter": {
        "id": "user_id",
        "username": "ServerOwner",
        "avatar": "avatar_hash"
      },
      "currentStatus": {
        "isOnline": true,
        "playerCount": 45,
        "maxPlayers": 100,
        "ping": 23
      }
    }
  ],
  "pagination": {...}
}

Get Game Server Details

Endpoint: GET /api/game-servers/:id

Returns detailed information about a game server.

Authentication: Not required

Response:

{
  "server": {
    "id": "server_id",
    "name": "Awesome Minecraft Server",
    "gameType": "minecraft",
    "ip": "play.example.com",
    "port": 25565,
    "description": "Best survival server!",
    "website": "https://example.com",
    "currentStatus": {...},
    "submitter": {...}
  }
}

Get Server Status History

Endpoint: GET /api/game-servers/:id/history

Returns historical status data for charts (last 24 hours).

Authentication: Not required

Response:

{
  "history": [
    {
      "timestamp": "2024-01-01T00:00:00.000Z",
      "isOnline": true,
      "playerCount": 45,
      "maxPlayers": 100,
      "ping": 23
    }
  ]
}

Submit Game Server

Endpoint: POST /api/game-servers

Submits a new game server for approval.

Authentication: Required

Request Body:

{
  "name": "My Minecraft Server",
  "gameType": "minecraft",
  "ip": "play.myserver.com",
  "port": 25565,
  "description": "A great survival server",
  "website": "https://myserver.com",
  "tags": "survival,economy",
  "linkedGuildId": "guild_id"
}

Response:

{
  "id": "server_id",
  "name": "My Minecraft Server",
  "isApproved": false,
  "createdAt": "2024-01-01T00:00:00.000Z"
}

Update Game Server

Endpoint: PATCH /api/game-servers/:id

Updates own game server information.

Authentication: Required (Owner)

Request Body:

{
  "description": "Updated description",
  "website": "https://newsite.com",
  "tags": "survival,economy,pvp"
}

Delete Game Server

Endpoint: DELETE /api/game-servers/:id

Deletes own game server.

Authentication: Required (Owner)

Response:

{
  "message": "Game server deleted successfully"
}

List Pending Game Servers (Moderator Only)

Endpoint: GET /api/game-servers/pending

Returns servers awaiting approval.

Authentication: Required (Moderator)

Query Parameters: Same as list game servers

Response:

{
  "servers": [...],
  "pagination": {...}
}

Approve Game Server (Moderator Only)

Endpoint: POST /api/game-servers/:id/approve

Approves a submitted game server.

Authentication: Required (Moderator)

Response:

{
  "id": "server_id",
  "isApproved": true,
  "approvedBy": "moderator_id",
  "approvedAt": "2024-01-01T00:00:00.000Z"
}

Reject Game Server (Moderator Only)

Endpoint: POST /api/game-servers/:id/reject

Rejects a submitted game server.

Authentication: Required (Moderator)

Request Body:

{
  "reason": "Server does not meet requirements"
}

Force Query Server (Moderator Only)

Endpoint: POST /api/game-servers/:id/query

Manually queries a game server for current status.

Authentication: Required (Moderator)

Response:

{
  "status": {
    "isOnline": true,
    "playerCount": 45,
    "maxPlayers": 100,
    "ping": 23
  }
}

Live Chat Endpoints

Get Chat Messages

Endpoint: GET /api/live-chat/messages

Returns recent chat messages (for initial load).

Authentication: Not required

Query Parameters:

limit (number, optional): Number of messages (default: 50, max: 100)

Response:

{
  "messages": [
    {
      "id": "message_id",
      "content": "Hello everyone!",
      "userId": "user_id",
      "isDeleted": false,
      "createdAt": "2024-01-01T00:00:00.000Z",
      "user": {
        "id": "user_id",
        "username": "PlayerOne",
        "avatar": "avatar_hash",
        "rank": {
          "rank": "MEMBER"
        }
      }
    }
  ]
}

Send Chat Message

Endpoint: POST /api/live-chat/messages

Sends a new chat message.

Authentication: Required

Rate Limit: 10 messages per minute

Request Body:

{
  "content": "Hello everyone!"
}

Response:

{
  "id": "message_id",
  "content": "Hello everyone!",
  "userId": "user_id",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "user": {...}
}

WebSocket Event: Broadcasts chat:message event to all connected clients

Delete Chat Message (Moderator Only)

Endpoint: DELETE /api/live-chat/messages/:id

Deletes a chat message (soft delete).

Authentication: Required (Moderator)

Response:

{
  "message": "Message deleted successfully"
}

WebSocket Event: Broadcasts chat:delete event with messageId

WebSocket Events

The platform uses Socket.IO for real-time features.

Connection: Automatic on user login via SocketContext

Authentication: Session-based (same as HTTP)

Chat Events

chat:message - New message received

{
  "id": "message_id",
  "content": "Hello!",
  "user": {...},
  "createdAt": "2024-01-01T00:00:00.000Z"
}

chat:delete - Message deleted

{
  "messageId": "message_id"
}

chat:typing - User is typing (client-to-server)

{
  "userId": "user_id",
  "username": "PlayerOne"
}

Error Codes

Code	Description
`UNAUTHORIZED`	Authentication required
`FORBIDDEN`	Insufficient permissions
`NOT_FOUND`	Resource not found
`VALIDATION_ERROR`	Invalid input data
`RATE_LIMIT_EXCEEDED`	Too many requests
`SERVER_ERROR`	Internal server error
`DISCORD_API_ERROR`	Discord API error
`DATABASE_ERROR`	Database operation failed

Postman Collection

Import the API into Postman:

Create a new collection named "DBK Gaming API"
Set collection variables:
- base_url: http://localhost:3001/api (or production URL)
Configure authentication to use cookies
Import endpoints from this documentation

Testing the API

Using curl

# Get current user (requires session cookie)
curl -X GET http://localhost:3001/api/auth/me \
  -H "Cookie: connect.sid=YOUR_SESSION_COOKIE" \
  -H "Content-Type: application/json"

# List public servers
curl -X GET "http://localhost:3001/api/servers?limit=10&offset=0"

# Update user profile
curl -X PATCH http://localhost:3001/api/users/123456789 \
  -H "Cookie: connect.sid=YOUR_SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{"bio":"Updated bio text"}'

Using JavaScript (fetch)

// Get current user
const response = await fetch('/api/auth/me', {
  credentials: 'include'
});
const data = await response.json();

// Update user profile
const response = await fetch('/api/users/123456789', {
  method: 'PATCH',
  credentials: 'include',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    bio: 'Updated bio text'
  })
});

Live Chat Endpoints

Get Chat Messages

Endpoint: GET /api/livechat/messages

Get paginated chat message history.

Authentication: Required

Query Parameters:

limit (number, optional): Number of messages to fetch (default: 50, max: 100)
before (string, optional): Cursor for pagination (message ID)

Response:

{
  "messages": [
    {
      "id": "msg_123",
      "content": "Hello everyone!",
      "createdAt": "2024-02-22T10:30:00.000Z",
      "user": {
        "id": "123456789",
        "username": "Player1",
        "avatar": "https://cdn.discordapp.com/avatars/..."
      }
    }
  ],
  "hasMore": true,
  "nextCursor": "msg_122"
}

Send Chat Message

Endpoint: POST /api/livechat/messages

Send a new chat message. If Discord sync is enabled, the message will be sent to the configured Discord channel via webhook.

Authentication: Required

Request Body:

{
  "content": "Hello everyone!"
}

Validation:

content: Required, string, 1-2000 characters, no excessive whitespace

Response:

{
  "message": {
    "id": "msg_124",
    "content": "Hello everyone!",
    "createdAt": "2024-02-22T10:35:00.000Z",
    "user": {
      "id": "123456789",
      "username": "Player1",
      "avatar": "https://cdn.discordapp.com/avatars/..."
    }
  }
}

Error Responses:

400 Bad Request: Invalid message content (empty, too long, or invalid format)
401 Unauthorized: Not logged in
429 Too Many Requests: Rate limit exceeded (max 10 messages per minute)

Discord Integration:

If livechat settings are enabled and webhook URL is configured, message is automatically sent to Discord
Displays user's username and avatar in Discord
Failures to send to Discord are logged but do not prevent message from being saved

Get Live Chat Settings

Endpoint: GET /api/admin/livechat-settings

Get current livechat configuration.

Authentication: Required
Permission: MANAGE_LIVECHAT_SETTINGS or MANAGE_SYSTEM

Response:

{
  "id": "singleton",
  "enabled": true,
  "webhookUrl": "https://discord.com/api/webhooks/...",
  "guildId": null,
  "channelId": null,
  "createdAt": "2024-02-20T12:00:00.000Z",
  "updatedAt": "2024-02-22T10:00:00.000Z"
}

Default Response (if no settings exist):

{
  "id": "singleton",
  "enabled": false,
  "webhookUrl": null,
  "guildId": null,
  "channelId": null,
  "createdAt": null,
  "updatedAt": null
}

Update Live Chat Settings

Endpoint: PATCH /api/admin/livechat-settings

Update livechat configuration.

Authentication: Required
Permission: MANAGE_LIVECHAT_SETTINGS or MANAGE_SYSTEM

Request Body:

{
  "enabled": true,
  "webhookUrl": "https://discord.com/api/webhooks/123456789/abcdef..."
}

Validation:

enabled (boolean, optional): Enable/disable Discord sync
webhookUrl (string, optional): Valid Discord webhook URL (must start with https://discord.com/api/webhooks/)

Response:

{
  "id": "singleton",
  "enabled": true,
  "webhookUrl": "https://discord.com/api/webhooks/...",
  "guildId": null,
  "channelId": null,
  "createdAt": "2024-02-20T12:00:00.000Z",
  "updatedAt": "2024-02-22T10:30:00.000Z"
}

Error Responses:

400 Bad Request: Invalid webhook URL format
401 Unauthorized: Not logged in
403 Forbidden: Insufficient permissions

Audit Logging: This action is logged in the audit trail with admin user ID and changes made.

Test Webhook

Endpoint: POST /api/admin/livechat-settings/test

Test a Discord webhook URL by sending a test message.

Authentication: Required
Permission: MANAGE_LIVECHAT_SETTINGS or MANAGE_SYSTEM

Request Body:

{
  "webhookUrl": "https://discord.com/api/webhooks/123456789/abcdef..."
}

Response (Success):

{
  "success": true,
  "message": "Test message sent successfully"
}

Response (Failure):

{
  "success": false,
  "error": "Invalid webhook URL or webhook was deleted"
}

Error Responses:

400 Bad Request: Invalid webhook URL format or webhook send failed
401 Unauthorized: Not logged in
403 Forbidden: Insufficient permissions

Notes:

Sends message as "LiveChat Settings Test" with content "Test message from LiveChat settings"
Does not save the webhook URL (use PATCH endpoint to save)
Useful for validating webhook URLs before saving

WebSocket Events

The backend provides real-time features via Socket.IO on the same port as the HTTP server.

Connection

Endpoint: wss://yourdomain.com or ws://localhost:3001

Authentication: Session cookie required (same as HTTP requests)

Client Connection:

import { io } from 'socket.io-client';

const socket = io('https://api.yourdomain.com', {
  withCredentials: true,
  transports: ['websocket', 'polling']
});

Events - Client to Server

Join Room

socket.emit('join:room', 'room-name');

Leave Room

socket.emit('leave:room', 'room-name');

Typing Indicator

socket.emit('chat:typing', {
  isTyping: true
});

Events - Server to Client

User Connected

socket.on('user:online', (data) => {
  // data: { userId: string, username: string }
});

User Disconnected

socket.on('user:offline', (data) => {
  // data: { userId: string, username: string }
});

Chat Message

socket.on('chat:message', (message) => {
  // message: { id, content, createdAt, user }
});

Typing Indicator

socket.on('chat:typing', (data) => {
  // data: { userId, username, isTyping: boolean }
});

Connection Error

socket.on('connect_error', (error) => {
  console.error('Connection error:', error.message);
});

API Versioning

Currently, the API is unversioned (v1 implicit). Future versions will be accessed via:

/api/v2/...
Header: Accept: application/vnd.dbk.v2+json

Support

For API issues or questions:

Check logs: npm run prod:logs
Report issues: GitHub Issues
Contact: [Your contact information]

API Documentation

API Documentation

Base URL

Authentication

Authentication Flow

Session Cookie

Rate Limiting

Response Format

Common HTTP Status Codes

Table of Contents

Authentication Endpoints

Login with Discord

OAuth Callback

Get Current User

Logout

User Endpoints

List Users (Admin Only)

Get User by ID

Update User

Delete User (Admin Only)

Members Endpoints

List Members

Get Member by ID

Server Endpoints

List Servers

Get Server by ID

Add Server

Update Server

Delete Server

Game Endpoints

List Games for Server

Add Game to Server

Delete Game from Server

Announcement Endpoints

List Announcements

Create Announcement (Admin Only)

Update Announcement (Admin Only)

Delete Announcement (Admin Only)

Admin Endpoints

Get Dashboard Statistics (Admin Only)

Get Audit Logs (Admin Only)

Update User Role (Admin Only)

Feature/Unfeature Server (Admin Only)

Get LiveChat Settings (Admin Only)

Update LiveChat Settings (Admin Only)

Test LiveChat Webhook (Admin Only)

Notification Endpoints

List User Notifications

Mark Notification as Read

Delete Notification

Search Endpoint

Global Search

AMP Server Endpoints

List AMP Servers

Get AMP Server by ID

Start AMP Server (Admin Only)

Stop AMP Server (Admin Only)

Force Sync AMP Servers (Admin Only)

Documentation Endpoints

List Documentation Files

Get Documentation Content

Rank Management Endpoints

List Users with Ranks (Admin Only)

Update User Rank (Admin Only)

List Available Permissions (Admin Only)

Grant Permission (Admin Only)

Revoke Permission (Admin Only)

Server Member Endpoints

List Server Members

Add Server Member

Update Server Member Rank

Remove Server Member

Forum Endpoints

List Forum Categories

Get Forum Category

Create Forum Category (Moderator Only)

Update Forum Category (Moderator Only)

Delete Forum Category (Admin Only)

List Forum Threads

Get Forum Thread