Servers
Register, update, disable, enable and remove the Discord servers MCDI knows about.
Discord server registration and lifecycle management - system admin only
List all servers
/api/serversReturns all registered servers with their current sync health data.
Authentication: Admin session token (Authorization: Bearer <token>)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
isActive | query | boolean | no | Filter by active/inactive status. |
isMain | query | boolean | no | Filter by main server status. |
type | query | string | no | Filter by server type (e.g. official, partner, other). |
name | query | string | no | Filter by server name (case-insensitive partial match). |
Responses
| Status | Description | Body |
|---|---|---|
200 | Servers retrieved successfully. | |
400 | Invalid parameter format. | |
401 | Authentication required. | |
403 | System admin access required. |
Open in Swagger (opens in a new tab)
Register a server
/api/serversRegisters a new Discord guild with MCDI (upsert by guild ID). Once registered, the server can be granted to projects and included in syncs.
Authentication: Admin session token (Authorization: Bearer <token>)
Request body (JSON, required): CreateServerDto schema.
Responses
| Status | Description | Body |
|---|---|---|
201 | Server registered successfully. | |
400 | Invalid request body. | |
401 | Authentication required. | |
403 | System admin access required. |
Open in Swagger (opens in a new tab)
Get a server by ID
/api/servers/{serverId}Returns a single server record by its Discord guild snowflake ID.
Authentication: Admin session token (Authorization: Bearer <token>)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
serverId | path | string | yes | Discord guild snowflake ID |
Responses
| Status | Description | Body |
|---|---|---|
200 | Server retrieved successfully. | |
400 | Invalid server ID format. | |
401 | Authentication required. | |
403 | System admin access required. | |
404 | Server not found. |
Open in Swagger (opens in a new tab)
Update server settings
/api/servers/{serverId}Updates the server name or other mutable settings.
Authentication: Admin session token (Authorization: Bearer <token>)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
serverId | path | string | yes | Discord guild snowflake ID |
Request body (JSON, required): UpdateServerDto schema.
Responses
| Status | Description | Body |
|---|---|---|
200 | Server updated successfully. | |
400 | Invalid request body. | |
401 | Authentication required. | |
403 | System admin access required. | |
404 | Server not found. |
Open in Swagger (opens in a new tab)
Delete a server
/api/servers/{serverId}Permanently removes a server and all associated data (members, roles, sync logs). This cannot be undone.
Authentication: Admin session token (Authorization: Bearer <token>)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
serverId | path | string | yes | Discord guild snowflake ID |
Responses
| Status | Description | Body |
|---|---|---|
204 | Server deleted successfully. | |
400 | Invalid server ID format. | |
401 | Authentication required. | |
403 | System admin access required. | |
404 | Server not found. |
Open in Swagger (opens in a new tab)
Disable a server
/api/servers/{serverId}/disableMarks the server as inactive. Disabled servers are excluded from syncs and all API permission/member checks return 403.
Authentication: Admin session token (Authorization: Bearer <token>)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
serverId | path | string | yes | Discord guild snowflake ID |
Request body (JSON, required): DisableServerDto schema.
Responses
| Status | Description | Body |
|---|---|---|
200 | Server disabled successfully. | |
400 | Invalid server ID format. | |
401 | Authentication required. | |
403 | System admin access required. | |
404 | Server not found. |
Open in Swagger (opens in a new tab)
Enable a server
/api/servers/{serverId}/enableRe-activates a previously disabled server.
Authentication: Admin session token (Authorization: Bearer <token>)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
serverId | path | string | yes | Discord guild snowflake ID |
Responses
| Status | Description | Body |
|---|---|---|
200 | Server enabled successfully. | |
400 | Invalid server ID format. | |
401 | Authentication required. | |
403 | System admin access required. | |
404 | Server not found. |
Open in Swagger (opens in a new tab)
Schemas
CreateServerDto schema
| Field | Type | Required | Description |
|---|---|---|---|
defaultPermissionPolicy | "deny_all" or "allow_all" or "custom" | no | Default: "deny_all". |
disabledReason | string or null | no | |
guildId | string | yes | Discord guild ID |
icon | string or null | no | |
isActive | boolean | no | Default: true. |
isMain | boolean | no | Default: false. |
name | string | no | |
syncFrequencyHours | number | no | Sync frequency in hours |
type | "main" or "competition" or "event" or "other" | no | Server category type Default: "other". |
DisableServerDto schema
| Field | Type | Required | Description |
|---|---|---|---|
disabledReason | string | no |
UpdateServerDto schema
| Field | Type | Required | Description |
|---|---|---|---|
defaultPermissionPolicy | "deny_all" or "allow_all" or "custom" | no | Default: "deny_all". |
icon | string or null | no | |
isMain | boolean | no | Default: false. |
name | string | no | |
syncFrequencyHours | number | no | Sync frequency in hours |
type | "main" or "competition" or "event" or "other" | no | Server category type Default: "other". |
Source: apps/api/openapi.json.