Community Administration API

Manage communities, departments, members, permissions, charges, custom domains, and platform-wide administration.

Authentication: Most endpoints require a valid JWT Bearer token via Authorization: Bearer <token>. Endpoints marked community admin require the user to hold an admin role within the target community. Endpoints marked Super Admin require platform-level administrator privileges.

1. Community Management

Core endpoints for creating, retrieving, and configuring communities. Each community maps to a Discord server via its guildId.

GET /api/community/mine authCheck

Returns all communities the authenticated user belongs to, including their role in each.

Response Example

{
  "communities": [
    {
      "_id": "64a1b2c3d4e5f6a7b8c9d0e1",
      "name": "San Andreas State RP",
      "guildId": "123456789012345678",
      "memberCount": 42,
      "role": "admin",
      "createdAt": "2025-08-15T10:30:00.000Z"
    },
    {
      "_id": "64a1b2c3d4e5f6a7b8c9d0e2",
      "name": "Liberty City PD",
      "guildId": "987654321098765432",
      "memberCount": 18,
      "role": "member",
      "createdAt": "2025-09-01T14:00:00.000Z"
    }
  ]
}

GET /api/community/:id authCheck

Retrieve a single community by its ID, including settings and member summary.

Path Parameters

Parameter	Type	Description
`id`	String	The community's unique ID.

Response Example

{
  "_id": "64a1b2c3d4e5f6a7b8c9d0e1",
  "name": "San Andreas State RP",
  "guildId": "123456789012345678",
  "memberCount": 42,
  "settings": {
    "dispatchRoleId": "111222333444555666",
    "cadSettings": { ... },
    "statusCodes": [ ... ]
  },
  "departments": [ ... ],
  "createdAt": "2025-08-15T10:30:00.000Z"
}

POST /api/community Super Admin

Create a new community linked to a Discord server. Only platform-level Super Admins can perform this action.

Request Body

Field	Type	Required	Description
`name`	String	Yes	Display name for the community.
`guildId`	String	Yes	Discord server (guild) ID to link.

Request Example

POST /api/community
Content-Type: application/json
Authorization: Bearer <super-admin-token>

{
  "name": "San Andreas State RP",
  "guildId": "123456789012345678"
}

Response Example

{
  "success": true,
  "community": {
    "_id": "64a1b2c3d4e5f6a7b8c9d0e1",
    "name": "San Andreas State RP",
    "guildId": "123456789012345678",
    "createdAt": "2025-08-15T10:30:00.000Z"
  }
}

PUT /api/community/:id/settings community admin

Update basic community settings such as the dispatch role assignment.

Request Body

Field	Type	Required	Description
`dispatchRoleId`	String	Yes	Discord role ID that grants dispatch access.

Request Example

PUT /api/community/64a1b2c3d4e5f6a7b8c9d0e1/settings
Content-Type: application/json

{
  "dispatchRoleId": "111222333444555666"
}

PUT /api/community/:id/members/:discordId/role community admin

Update a member's role within the community. Available roles are member, supervisor, and admin.

Path Parameters

Parameter	Type	Description
`id`	String	Community ID.
`discordId`	String	Target member's Discord user ID.

Request Body

Field	Type	Required	Description
`role`	String	Yes	One of: `member`, `supervisor`, `admin`.

Request Example

PUT /api/community/64a1b.../members/998877665544332211/role
Content-Type: application/json

{
  "role": "supervisor"
}

GET /api/community/:guildId/roles authCheck

Fetch all Discord roles for the specified guild. Useful for populating role selection dropdowns in community settings.

Path Parameters

Parameter	Type	Description
`guildId`	String	Discord guild (server) ID.

Response Example

{
  "roles": [
    { "id": "111222333444555666", "name": "Admin", "color": "#e74c3c" },
    { "id": "222333444555666777", "name": "Moderator", "color": "#3498db" },
    { "id": "333444555666777888", "name": "Dispatcher", "color": "#2ecc71" }
  ]
}

2. Community Admin Panel

Advanced administration endpoints for community settings, statistics, and member management. All endpoints in this group require community admin authorization unless otherwise noted.

GET /api/community-admin/settings community admin

Retrieve the full settings object for a community, including CAD configuration, status codes, jurisdiction, and custom sounds.

Query Parameters

Parameter	Type	Required	Description
`communityId`	String	Yes	Target community ID.

Response Example

{
  "settings": {
    "communityId": "64a1b2c3d4e5f6a7b8c9d0e1",
    "cadSettings": {
      "enableCivilian": true,
      "enableJudicial": true,
      "enableLivemap": true,
      "darkMode": true
    },
    "statusCodes": [
      { "code": "10-8", "label": "In Service" },
      { "code": "10-7", "label": "Out of Service" },
      { "code": "10-6", "label": "Busy" }
    ],
    "jurisdiction": "San Andreas",
    "licenseFormat": "SA-######",
    "boloPermission": "supervisor",
    "pointsThreshold": 12,
    "customSounds": {
      "alert911": "https://cdn.example.com/sounds/911.mp3",
      "bolo": "https://cdn.example.com/sounds/bolo.mp3",
      "panic": "https://cdn.example.com/sounds/panic.mp3",
      "announcement": null,
      "dispatch": null
    }
  }
}

PUT /api/community-admin/settings community admin

Update community settings. All setting fields are optional; only provided fields are updated (partial update). The communityId field is required to identify the target community.

Request Body

Field	Type	Required	Description
`communityId`	String	Yes	Target community ID.
`cadSettings`	Object	No	CAD feature toggles (enableCivilian, enableJudicial, enableLivemap, etc.).
`statusCodes`	Array	No	Array of status code objects with `code` and `label`.
`jurisdiction`	String	No	Community jurisdiction label.
`licenseFormat`	String	No	License plate format pattern (e.g. `SA-######`).
`boloPermission`	String	No	Minimum role to create BOLOs: `member`, `supervisor`, or `admin`.
`pointsThreshold`	Number	No	Points threshold for automatic license suspension.
`customSounds`	Object	No	Custom notification sound URLs. Keys: `alert911`, `bolo`, `panic`, `announcement`, `dispatch`, etc.

Request Example

PUT /api/community-admin/settings
Content-Type: application/json

{
  "communityId": "64a1b2c3d4e5f6a7b8c9d0e1",
  "cadSettings": {
    "enableCivilian": true,
    "enableLivemap": false
  },
  "pointsThreshold": 15,
  "customSounds": {
    "panic": "https://cdn.example.com/sounds/custom-panic.mp3"
  }
}

Response Example

{
  "success": true,
  "msg": "Community settings updated successfully."
}

GET /api/community-admin/stats community admin

Retrieve aggregated statistics for a community, including member counts, active calls, reports filed, and more.

Query Parameters

Parameter	Type	Required	Description
`communityId`	String	Yes	Target community ID.

Response Example

{
  "stats": {
    "totalMembers": 42,
    "activeMembers": 28,
    "totalCivilians": 156,
    "totalVehicles": 312,
    "totalCalls": 1847,
    "activeCalls": 3,
    "totalReports": 524,
    "totalArrests": 189,
    "totalCitations": 376,
    "departmentBreakdown": [
      { "name": "LSPD", "memberCount": 18 },
      { "name": "BCSO", "memberCount": 12 },
      { "name": "SASP", "memberCount": 8 }
    ]
  }
}

GET /api/community-admin/members community admin

List all members of a community with their roles, departments, and activity status.

Query Parameters

Parameter	Type	Required	Description
`communityId`	String	Yes	Target community ID.

Response Example

{
  "members": [
    {
      "_id": "65b2c3d4e5f6a7b8c9d0e1f2",
      "username": "Officer_Smith",
      "discordId": "112233445566778899",
      "role": "admin",
      "department": "LSPD",
      "joinedAt": "2025-08-15T10:30:00.000Z",
      "lastActive": "2026-02-27T22:15:00.000Z"
    },
    {
      "_id": "65b2c3d4e5f6a7b8c9d0e1f3",
      "username": "Deputy_Jones",
      "discordId": "998877665544332211",
      "role": "member",
      "department": "BCSO",
      "joinedAt": "2025-09-01T14:00:00.000Z",
      "lastActive": "2026-02-26T18:45:00.000Z"
    }
  ]
}

POST /api/community-admin/members community admin

Add a new member to the community with a specified role and department assignment.

Request Body

Field	Type	Required	Description
`communityId`	String	Yes	Target community ID.
`username`	String	Yes	Display name for the member.
`discordId`	String	Yes	Member's Discord user ID.
`role`	String	Yes	Role: `member`, `supervisor`, or `admin`.
`department`	String	Yes	Department name or ID to assign.

Request Example

POST /api/community-admin/members
Content-Type: application/json

{
  "communityId": "64a1b2c3d4e5f6a7b8c9d0e1",
  "username": "Trooper_Davis",
  "discordId": "554433221100998877",
  "role": "member",
  "department": "SASP"
}

Response Example

{
  "success": true,
  "member": {
    "_id": "65b2c3d4e5f6a7b8c9d0e1f4",
    "username": "Trooper_Davis",
    "discordId": "554433221100998877",
    "role": "member",
    "department": "SASP",
    "joinedAt": "2026-02-28T12:00:00.000Z"
  }
}

DELETE /api/community-admin/members/:id community admin

Remove a member from the community. This does not ban the user from Discord — it only revokes their CAD access.

Path Parameters

Parameter	Type	Description
`id`	String	The member record ID to remove.

Query Parameters

Parameter	Type	Required	Description
`communityId`	String	Yes	Target community ID.

Response Example

{
  "success": true,
  "msg": "Member removed from community."
}

PUT /api/community-admin/members/:id/role community admin

Update a member's role within the community via the admin panel.

Path Parameters

Parameter	Type	Description
`id`	String	The member record ID.

Request Body

Field	Type	Required	Description
`communityId`	String	Yes	Target community ID.
`role`	String	Yes	New role: `member`, `supervisor`, or `admin`.

Request Example

PUT /api/community-admin/members/65b2c3d4e5f6a7b8c9d0e1f3/role
Content-Type: application/json

{
  "communityId": "64a1b2c3d4e5f6a7b8c9d0e1",
  "role": "supervisor"
}

Response Example

{
  "success": true,
  "msg": "Member role updated to supervisor."
}

3. Departments

Departments represent organizational units within a community (e.g. LSPD, BCSO, EMS). Each department can be linked to a Discord role, have its own logo, and receive webhook notifications.

GET /api/departments authCheck

List all departments for a community.

Query Parameters

Parameter	Type	Required	Description
`communityId`	String	Yes	Target community ID.

Response Example

{
  "departments": [
    {
      "_id": "66c3d4e5f6a7b8c9d0e1f2a3",
      "name": "Los Santos Police Department",
      "shortName": "LSPD",
      "discordRoleId": "111222333444555666",
      "isAdmin": false,
      "logo": "https://cdn.cdecad.com/logos/lspd.png",
      "webhookUrl": "https://discord.com/api/webhooks/...",
      "communityId": "64a1b2c3d4e5f6a7b8c9d0e1",
      "memberCount": 18
    },
    {
      "_id": "66c3d4e5f6a7b8c9d0e1f2a4",
      "name": "Blaine County Sheriff's Office",
      "shortName": "BCSO",
      "discordRoleId": "222333444555666777",
      "isAdmin": false,
      "logo": "https://cdn.cdecad.com/logos/bcso.png",
      "webhookUrl": null,
      "communityId": "64a1b2c3d4e5f6a7b8c9d0e1",
      "memberCount": 12
    }
  ]
}

POST /api/departments community admin

Create a new department within a community. The logo field accepts a base64-encoded image string.

Request Body

Field	Type	Required	Description
`name`	String	Yes	Full department name.
`shortName`	String	Yes	Abbreviated name (e.g. `LSPD`).
`discordRoleId`	String	No	Discord role ID to associate with this department.
`isAdmin`	Boolean	No	Whether this department grants admin-level permissions. Default: `false`.
`logo`	String	No	Base64-encoded image for the department logo.
`webhookUrl`	String	No	Discord webhook URL for department notifications.
`communityId`	String	Yes	Target community ID.

Request Example

POST /api/departments
Content-Type: application/json

{
  "name": "San Andreas State Police",
  "shortName": "SASP",
  "discordRoleId": "333444555666777888",
  "isAdmin": false,
  "logo": "data:image/png;base64,iVBORw0KGgo...",
  "webhookUrl": "https://discord.com/api/webhooks/...",
  "communityId": "64a1b2c3d4e5f6a7b8c9d0e1"
}

Response Example

{
  "success": true,
  "department": {
    "_id": "66c3d4e5f6a7b8c9d0e1f2a5",
    "name": "San Andreas State Police",
    "shortName": "SASP",
    "discordRoleId": "333444555666777888",
    "isAdmin": false,
    "communityId": "64a1b2c3d4e5f6a7b8c9d0e1"
  }
}

PUT /api/departments/:id community admin

Update an existing department. Accepts the same body fields as creation. Only provided fields are updated.

Path Parameters

Parameter	Type	Description
`id`	String	Department ID to update.

Request Body

Field	Type	Required	Description
`name`	String	No	Full department name.
`shortName`	String	No	Abbreviated name.
`discordRoleId`	String	No	Discord role ID.
`isAdmin`	Boolean	No	Whether this department grants admin privileges.
`logo`	String	No	Base64-encoded image.
`webhookUrl`	String	No	Discord webhook URL.
`communityId`	String	Yes	Target community ID.

Request Example

PUT /api/departments/66c3d4e5f6a7b8c9d0e1f2a5
Content-Type: application/json

{
  "name": "San Andreas Highway Patrol",
  "shortName": "SAHP",
  "communityId": "64a1b2c3d4e5f6a7b8c9d0e1"
}

DELETE /api/departments/:id community admin

Delete a department from the community. Members assigned to this department will need to be reassigned.

Path Parameters

Parameter	Type	Description
`id`	String	Department ID to delete.

Query Parameters

Parameter	Type	Required	Description
`communityId`	String	Yes	Target community ID.

Response Example

{
  "success": true,
  "msg": "Department deleted successfully."
}

GET /api/departments/user/:communityId authCheck

Get the departments that the authenticated user belongs to within a specific community.

Path Parameters

Parameter	Type	Description
`communityId`	String	Community ID to query.

Response Example

{
  "departments": [
    {
      "_id": "66c3d4e5f6a7b8c9d0e1f2a3",
      "name": "Los Santos Police Department",
      "shortName": "LSPD",
      "isAdmin": false
    }
  ]
}

4. Charges

Manage the penal code and charge definitions for a community. Charges are referenced when creating citations, arrests, and warrants. Each charge has a severity level, fine amount, jail time, and points value.

GET /api/charges authCheck

List all charges for a community. Supports filtering by severity and search terms.

Query Parameters

Parameter	Type	Required	Description
`communityId`	String	Yes	Target community ID.
`severity`	String	No	Filter by severity: `infraction`, `misdemeanor`, `felony`.
`search`	String	No	Search charges by code or description.

Response Example

{
  "charges": [
    {
      "_id": "67d4e5f6a7b8c9d0e1f2a3b4",
      "code": "PC-001",
      "description": "Speeding (1-15 mph over)",
      "severity": "infraction",
      "fine": 150,
      "jailTime": 0,
      "points": 1,
      "communityId": "64a1b2c3d4e5f6a7b8c9d0e1"
    },
    {
      "_id": "67d4e5f6a7b8c9d0e1f2a3b5",
      "code": "PC-042",
      "description": "Grand Theft Auto",
      "severity": "felony",
      "fine": 5000,
      "jailTime": 60,
      "points": 4,
      "communityId": "64a1b2c3d4e5f6a7b8c9d0e1"
    }
  ]
}

POST /api/charges authCheck

Create a new charge definition.

Request Body

Field	Type	Required	Description
`code`	String	Yes	Charge code (e.g. `PC-001`).
`description`	String	Yes	Human-readable description of the charge.
`severity`	String	Yes	Severity level: `infraction`, `misdemeanor`, or `felony`.
`fine`	Number	Yes	Fine amount in dollars.
`jailTime`	Number	Yes	Jail time in minutes.
`points`	Number	Yes	License points assessed.

Request Example

POST /api/charges
Content-Type: application/json

{
  "code": "PC-015",
  "description": "Reckless Driving",
  "severity": "misdemeanor",
  "fine": 1500,
  "jailTime": 15,
  "points": 3
}

POST /api/charges/import authCheck

Bulk import multiple charges at once. Accepts an array of charge objects. Useful for initial community setup or migrating penal codes from another system.

Request Example

POST /api/charges/import
Content-Type: application/json

{
  "communityId": "64a1b2c3d4e5f6a7b8c9d0e1",
  "charges": [
    {
      "code": "PC-001",
      "description": "Speeding (1-15 mph over)",
      "severity": "infraction",
      "fine": 150,
      "jailTime": 0,
      "points": 1
    },
    {
      "code": "PC-002",
      "description": "Speeding (16-25 mph over)",
      "severity": "infraction",
      "fine": 350,
      "jailTime": 0,
      "points": 2
    },
    {
      "code": "PC-010",
      "description": "Assault with a Deadly Weapon",
      "severity": "felony",
      "fine": 7500,
      "jailTime": 90,
      "points": 0
    }
  ]
}

Response Example

{
  "success": true,
  "imported": 3,
  "msg": "3 charges imported successfully."
}

PUT /api/charges/:id authCheck

Update an existing charge definition. Only provided fields are modified.

Path Parameters

Parameter	Type	Description
`id`	String	Charge ID to update.

Request Example

PUT /api/charges/67d4e5f6a7b8c9d0e1f2a3b4
Content-Type: application/json

{
  "fine": 200,
  "points": 2
}

DELETE /api/charges/:id authCheck

Delete a single charge by ID.

Path Parameters

Parameter	Type	Description
`id`	String	Charge ID to delete.

Response Example

{
  "success": true,
  "msg": "Charge deleted."
}

DELETE /api/charges/bulk authCheck

Delete multiple charges at once. Provide an array of charge IDs.

Request Body

Field	Type	Required	Description
`chargeIds`	Array<String>	Yes	Array of charge IDs to delete.

Request Example

DELETE /api/charges/bulk
Content-Type: application/json

{
  "chargeIds": [
    "67d4e5f6a7b8c9d0e1f2a3b4",
    "67d4e5f6a7b8c9d0e1f2a3b5",
    "67d4e5f6a7b8c9d0e1f2a3b6"
  ]
}

Response Example

{
  "success": true,
  "deleted": 3,
  "msg": "3 charges deleted."
}

5. Permissions & Discord Role Mapping

CDE CAD permissions are driven by Discord role associations configured at the community level. The communityPermissions object on a community defines which Discord roles map to CAD permission levels.

Key concept: When a user authenticates via Discord OAuth, their guild roles are inspected and matched against the community's role mappings. This determines what level of access they receive in the CAD.

Permission Role Fields

Field	Type	Description
`communityAdminRoleId`	String	Discord role ID that grants full community admin access. Users with this role can manage settings, departments, members, and all community configuration.
`judicialRoleId`	String	Discord role ID that grants judicial permissions. Users with this role can manage warrants, approve court requests, and handle license suspensions.
`supervisorRoleIds`	Array<String>	Array of Discord role IDs that grant supervisor-level access. Supervisors can manage BOLOs, approve reports, and oversee dispatch operations.
`dispatchRoleId`	String	Discord role ID that grants dispatch access. Users with this role can manage calls, assign units, and operate the dispatch board.
`autoSyncRoles`	Boolean	When `true`, CAD permissions are automatically updated whenever a user's Discord roles change. Default: `false`.

Auto-Sync Behavior

When autoSyncRoles is enabled, the following behavior applies:

Discord role changes are detected when the user next authenticates or when a manual sync is triggered.
If a user gains the communityAdminRoleId in Discord, they are automatically promoted to community admin in CAD.
If a user loses a mapped role in Discord, the corresponding CAD permission is revoked.
The supervisorRoleIds array supports multiple roles — a user holding any of the listed roles receives supervisor access.

Warning: When autoSyncRoles is enabled, manually assigned CAD roles may be overridden on the next sync. Use manual role assignment only when auto-sync is disabled.

Configuration Example

PUT /api/community-admin/settings
Content-Type: application/json

{
  "communityId": "64a1b2c3d4e5f6a7b8c9d0e1",
  "communityPermissions": {
    "communityAdminRoleId": "111222333444555666",
    "judicialRoleId": "222333444555666777",
    "supervisorRoleIds": [
      "333444555666777888",
      "444555666777888999"
    ],
    "dispatchRoleId": "555666777888999000",
    "autoSyncRoles": true
  }
}

6. Custom Domains

Communities can configure custom domains or subdomains to brand their CAD instance. Subdomains under cdecad.com are provisioned automatically. Fully custom domains require DNS verification.

POST /api/domains/:communityId/subdomain community admin

Set up a subdomain under cdecad.com for the community (e.g. myserver.cdecad.com). The subdomain is provisioned automatically with no DNS configuration needed.

Path Parameters

Parameter	Type	Description
`communityId`	String	Target community ID.

Request Body

Field	Type	Required	Description
`subdomain`	String	Yes	Desired subdomain name (alphanumeric and hyphens only).

Request Example

POST /api/domains/64a1b2c3d4e5f6a7b8c9d0e1/subdomain
Content-Type: application/json

{
  "subdomain": "myserver"
}

Response Example

{
  "success": true,
  "domain": "myserver.cdecad.com",
  "msg": "Subdomain configured. Your CAD is now accessible at https://myserver.cdecad.com"
}

POST /api/domains/:communityId/custom community admin

Configure a fully custom domain for the community (e.g. cad.myserver.com). After setup, you must verify DNS ownership using the /verify endpoint.

Path Parameters

Parameter	Type	Description
`communityId`	String	Target community ID.

Request Body

Field	Type	Required	Description
`domain`	String	Yes	Fully qualified custom domain name.

Request Example

POST /api/domains/64a1b2c3d4e5f6a7b8c9d0e1/custom
Content-Type: application/json

{
  "domain": "cad.myserver.com"
}

Response Example

{
  "success": true,
  "domain": "cad.myserver.com",
  "status": "pending_verification",
  "dnsRecords": [
    {
      "type": "CNAME",
      "name": "cad",
      "value": "custom.cdecad.com"
    },
    {
      "type": "TXT",
      "name": "_cdecad-verify",
      "value": "cdecad-verify=abc123def456"
    }
  ],
  "msg": "Custom domain registered. Add the DNS records below to your domain provider, then call the /verify endpoint."
}

DNS Setup: After registering a custom domain, add both the CNAME and TXT verification records to your domain's DNS configuration. DNS propagation may take up to 48 hours.

POST /api/domains/:communityId/verify community admin

Verify DNS configuration for a custom domain. Checks that the required CNAME and TXT records are properly configured.

Path Parameters

Parameter	Type	Description
`communityId`	String	Target community ID.

Response Example (Success)

{
  "success": true,
  "domain": "cad.myserver.com",
  "status": "verified",
  "sslStatus": "provisioning",
  "msg": "Domain verified! SSL certificate is being provisioned. Your CAD will be accessible at https://cad.myserver.com within a few minutes."
}

Response Example (Failure)

{
  "success": false,
  "domain": "cad.myserver.com",
  "status": "pending_verification",
  "errors": [
    "CNAME record not found. Expected: cad.myserver.com -> custom.cdecad.com",
    "TXT verification record not found."
  ],
  "msg": "DNS verification failed. Please check your DNS records and try again."
}

DELETE /api/domains/:communityId/subdomain community admin

Remove a configured subdomain from the community. The community will revert to being accessible only via the default CDE CAD URL.

Path Parameters

Parameter	Type	Description
`communityId`	String	Target community ID.

Response Example

{
  "success": true,
  "msg": "Subdomain removed."
}

7. Super Admin

Platform-level administration endpoints. These are restricted to CDE CAD Super Administrators and provide oversight across all users and communities on the platform.

Restricted Access: Super Admin endpoints require platform-level administrator privileges. These are not community-scoped — they operate across the entire CDE CAD platform. Misuse of these endpoints can affect all users and communities.

GET /api/admin/users Super Admin

Retrieve a paginated list of all users across the platform. Supports filtering and sorting.

Query Parameters

Parameter	Type	Required	Default	Description
`page`	Number	No	`1`	Page number for pagination.
`limit`	Number	No	`25`	Number of users per page (max 100).
`search`	String	No	—	Search by username or Discord ID.
`sortBy`	String	No	`createdAt`	Sort field: `createdAt`, `username`, `lastActive`.
`isAdmin`	Boolean	No	—	Filter by admin status.
`isActive`	Boolean	No	—	Filter by active status.

Response Example

{
  "users": [
    {
      "_id": "68e5f6a7b8c9d0e1f2a3b4c5",
      "username": "Officer_Smith",
      "discordId": "112233445566778899",
      "isAdmin": false,
      "isActive": true,
      "communities": ["64a1b2c3d4e5f6a7b8c9d0e1"],
      "createdAt": "2025-08-15T10:30:00.000Z",
      "lastActive": "2026-02-27T22:15:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "totalPages": 12,
    "totalUsers": 287
  }
}

GET /api/admin/communities Super Admin

Retrieve a paginated list of all communities on the platform. Supports filtering by status and search.

Query Parameters

Parameter	Type	Required	Default	Description
`page`	Number	No	`1`	Page number.
`limit`	Number	No	`25`	Results per page (max 100).
`search`	String	No	—	Search by community name or guild ID.
`status`	String	No	—	Filter by status: `active`, `inactive`, `suspended`.

Response Example

{
  "communities": [
    {
      "_id": "64a1b2c3d4e5f6a7b8c9d0e1",
      "name": "San Andreas State RP",
      "guildId": "123456789012345678",
      "status": "active",
      "memberCount": 42,
      "departmentCount": 4,
      "createdAt": "2025-08-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "totalPages": 3,
    "totalCommunities": 64
  }
}

GET /api/admin/stats Super Admin

Retrieve platform-wide system statistics, including total users, communities, calls, and reports. Supports timeframe filtering.

Query Parameters

Parameter	Type	Required	Default	Description
`timeframe`	String	No	`30d`	Time window for statistics: `24h`, `7d`, `30d`, `90d`, `all`.

Response Example

{
  "stats": {
    "timeframe": "30d",
    "users": {
      "total": 287,
      "active": 198,
      "newThisPeriod": 34
    },
    "communities": {
      "total": 64,
      "active": 52,
      "newThisPeriod": 5
    },
    "calls": {
      "total": 12847,
      "thisPeriod": 3291
    },
    "reports": {
      "total": 4523,
      "thisPeriod": 867
    },
    "arrests": {
      "total": 1893,
      "thisPeriod": 412
    }
  }
}

POST /api/admin/users/bulk-action Super Admin

Perform a bulk action on multiple users. Supported actions include deletion, admin promotion/demotion, and account deactivation.

Request Body

Field	Type	Required	Description
`action`	String	Yes	Action to perform: `delete`, `makeAdmin`, `removeAdmin`, `deactivate`.
`userIds`	Array<String>	Yes	Array of user IDs to act upon.
`reason`	String	No	Reason for the action (logged for audit trail).

Request Example

POST /api/admin/users/bulk-action
Content-Type: application/json

{
  "action": "deactivate",
  "userIds": [
    "68e5f6a7b8c9d0e1f2a3b4c5",
    "68e5f6a7b8c9d0e1f2a3b4c6",
    "68e5f6a7b8c9d0e1f2a3b4c7"
  ],
  "reason": "Inactive accounts - no login in 90+ days"
}

Response Example

{
  "success": true,
  "action": "deactivate",
  "affected": 3,
  "msg": "3 users deactivated successfully."
}

Audit Trail: All Super Admin actions are logged with timestamps, the acting admin's ID, and the provided reason. Always include a descriptive reason for bulk actions.

Bulk Action Reference

Action	Description	Reversible
`delete`	Permanently removes user accounts and all associated data.	No
`makeAdmin`	Grants platform-level Super Admin privileges to the specified users.	Yes
`removeAdmin`	Revokes platform-level Super Admin privileges.	Yes
`deactivate`	Disables user accounts. Users cannot log in but data is preserved.	Yes