Admin REST API — User, Match, and Bot Management

The Admin API exposes every management operation available in the bot’s web panel — from linking Discord accounts to Faceit profiles, to toggling feature flags, inspecting active matches, and broadcasting messages to all verified users. All routes are mounted under /api/admin and are protected by the verifyAdminToken middleware.

Every endpoint listed here requires the auth_token or admin_token JWT cookie issued by the Auth API. Missing cookies return 401 No autenticado. A cookie present but whose payload lacks role: admin | global_admin or isAdmin: true returns 403 No autorizado.

Guild Targeting

Most write and list operations are automatically scoped to the requesting user’s guild:

admin role — always scoped to req.user.servidor (the guild ID embedded in the JWT). The guildId parameter is ignored for scope resolution.
global_admin role — can target any guild by supplying a guildId.

You can pass a guild ID in any of these three ways (checked in order):

guildId

string

URL query parameter: ?guildId=123456789

x-guild-id

string

Request header: x-guild-id: 123456789

guildId

string

JSON body field: { "guildId": "123456789" }

System

GET /api/admin/me

Returns the decoded JWT payload for the currently authenticated user. Response

{
  "user": {
    "userId": "313886359448453120",
    "username": "someuser",
    "avatar": "a_deadbeef1234",
    "isAdmin": true,
    "role": "global_admin",
    "servidor": null,
    "iat": 1700000000,
    "exp": 1700028800
  }
}

GET /api/admin/system

Returns the process uptime in seconds and the Faceit hub region resolved from the effective configuration. Response

{
  "uptimeSeconds": 86423.7,
  "hubRegion": "EU"
}

uptimeSeconds

number

Seconds since the Node.js process started (process.uptime()).

hubRegion

string

Region string from the Faceit Hub API (uppercased), or "Desconocida" if no hub is configured.

GET /api/admin/status

Returns Discord connection status, guild metadata, and memory usage for the target guild. Response

{
  "discordConnected": true,
  "guildName": "Mi Servidor",
  "guildMemberCount": 412,
  "uptime": 86423.7,
  "memory": {
    "rss": 98304000,
    "heapTotal": 65536000,
    "heapUsed": 51234000,
    "external": 1024000
  }
}

GET /health

Public endpoint — no authentication required. Returns a minimal health object for uptime monitors. Response

{
  "status": "ok",
  "discord": "connected",
  "uptime": 86423.7,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Users

GET /api/admin/users

Lists all linked users in Firestore, filtered to the resolved guild. Each entry includes the Firestore document fields plus a clubRole string resolved from the member’s Discord roles (one of EXTREME, EXTREME BAJOS, PREMIUM, PLUS, or null). Response

{
  "users": [
    {
      "discordId": "123456789012345678",
      "faceit_player_id": "abcdef01-...",
      "faceit_nickname": "PlayerOne",
      "faceit_level": 8,
      "faceit_elo": 1850,
      "guild_id": "987654321098765432",
      "clubRole": "PREMIUM"
    }
  ]
}

POST /api/admin/users/verify

Manually links a Discord account to a Faceit profile. Fetches the player from the Faceit API, checks for duplicate links, saves the record to Firestore, and immediately syncs the Faceit level role in Discord. Request Body

discordId

string

required

Discord user ID (snowflake) of the member to link.

faceitNickname

string

required

Exact Faceit username of the player.

Response

{
  "success": true,
  "player": {
    "id": "abcdef01-1234-5678-abcd-ef0123456789",
    "nickname": "PlayerOne",
    "level": 8
  }
}

POST /api/admin/users/:id/unlink

Unlinks a user by their Discord ID. Removes all Faceit level roles and club roles from the member in Discord before deleting the Firestore document. Path Parameter

string

required

Discord user ID to unlink.

Response

{ "success": true }

POST /api/admin/users/sync-all

Triggers a background job that iterates every user in Firestore, re-fetches their current Faceit level, and syncs their Discord roles. The HTTP response is returned immediately; syncing continues in the background at a rate of one user per 150 ms. Response

{
  "success": true,
  "message": "Sincronización global iniciada en segundo plano para 87 usuarios."
}

GET /api/admin/users/backup

Downloads the entire faceit_users Firestore collection as a JSON array. Useful for migrations or manual backups. Response — raw JSON array of user objects.

POST /api/admin/users/restore

Restores user records from a previously exported backup. Uses a Firestore batch set with merge: true so existing records are updated rather than replaced. Request Body

users

array

required

Array of user objects exported from the /backup endpoint. Each object must contain a discordId field.

Response

{
  "success": true,
  "message": "Backup importado con éxito: 87 vinculaciones restauradas."
}

POST /api/admin/users/:id/roles

Assigns a Discord role (level or special) to a member. Level roles (Faceit Level 1 – Faceit Level 10) are mutually exclusive; special roles (EXTREME, PREMIUM, etc.) are additive. Path Parameter

string

required

Discord user ID.

Request Body

roleType

string

required

Either "level" or "special".

roleValue

string | number

required

For "level": integer 1–10. For "special": role name string (e.g. "EXTREME").

Response

{ "success": true }

POST /api/admin/users/:id/admin-role

Sets a user’s web panel role in Firestore. admin role requires a guildId; global_admin may only be assigned by another global_admin. Path Parameter

string

required

Discord user ID of the target user.

Request Body

role

string

required

One of "usuario", "admin", or "global_admin".

guildId

string

Guild ID the admin role is scoped to. Required when role is "admin".

Response

{ "success": true }

Matches

GET /api/admin/matches

Returns all active matches from Firestore, filtered to the resolved guild, along with computed server load metrics. Response

{
  "matches": [
    {
      "id": "1-abc123",
      "entity_custom_name": "Club",
      "game": "cs2",
      "map": "de_dust2",
      "faction1_name": "Team Alpha",
      "faction2_name": "Team Beta",
      "startedAt": 1700000000000,
      "guild_id": "987654321098765432"
    }
  ],
  "stats": {
    "serverLoad": 20.0,
    "avgDurationStr": "14m 23s",
    "failedCleanups": 0
  }
}

stats.serverLoad

number

Percentage of the estimated capacity (10 concurrent matches) that is currently in use.

stats.failedCleanups

number

Count of orphaned voice channels (name starts with 🔊) that have no corresponding active match.

POST /api/admin/matches/:id/cleanup

Force-removes an active match. Moves any connected voice-channel members back to the waiting room, deletes the two faction voice channels, and removes the match document from Firestore. Path Parameter

string

required

Faceit match ID to clean up.

Response

{ "success": true }

GET /api/admin/matches/history

Returns paginated match history sorted by creation date descending. Query Parameters

limit

number

Maximum number of records to return. Defaults to 20.

Response

{
  "history": [
    {
      "id": "1-abc123",
      "map": "de_mirage",
      "winner": "faction1",
      "faction1_score": 13,
      "faction2_score": 7,
      "createdAt": { "_seconds": 1700000000 }
    }
  ]
}

Leaderboard & Stats

GET /api/admin/leaderboard

Fetches the current leaderboard from the Faceit API and cross-references it with Discord IDs stored in Firestore. Response

{
  "leaderboard": [
    {
      "id": "faceit-uuid",
      "discord_id": "123456789012345678",
      "faceit_nickname": "PlayerOne",
      "faceit_level": 10,
      "faceit_elo": 3241
    }
  ]
}

Returns { "leaderboard": [] } if no leaderboard ID is configured.

GET /api/admin/stats/:nickname

Fetches a player’s Faceit profile, lifetime stats, and recent match history (last 10 matches). Path Parameter

nickname

string

required

Exact Faceit username.

Response

{
  "player": {
    "player_id": "abcdef01-...",
    "nickname": "PlayerOne",
    "avatar": "https://cdn.faceit.com/...",
    "country": "es",
    "level": 8,
    "elo": 1850,
    "role": "LVL 8"
  },
  "stats": { "...": "Faceit lifetime stats object" },
  "history": [ "...last 10 match objects..." ]
}

Returns 404 if the player is not found on Faceit.

Settings & Features

GET /api/admin/settings

Returns the full global settings document from Firestore merged with .env fallbacks. Requires global_admin role. Response

{
  "settings": {
    "discordGuildId": "987654321098765432",
    "discordMatchesChannelId": "111222333444555666",
    "faceitHubId": "hub-uuid",
    "adminRoleName": "ADMIN",
    "matchTimeoutMinutes": 120,
    "autoWelcomeDm": true,
    "autoRoleSync": true,
    "liveMatchPanel": true
  }
}

POST /api/admin/settings

Saves global settings by writing to the .env file on disk and updating in-memory process.env. Requires global_admin role. Also triggers an automatic re-deploy of the support panel channel. Request Body — settings object with any combination of the following keys:

discordGuildId

string

Discord primary guild ID.

discordLinkChannelId

string

Channel ID for /verificar_fc.

discordMatchesChannelId

string

Match announcements channel ID.

discordRolesChannelId

string

Role change notifications channel ID.

discordStatusChannelId

string

Server status embed channel ID.

discordWaitingRoomChannelId

string

Waiting room voice channel ID.

discordAdminAlertsChannelId

string

Staff alerts channel ID.

discordSupportChannelId

string

Support panel channel ID.

faceitHubId

string

Faceit Hub UUID.

faceitLeaderboardId

string

Faceit Leaderboard UUID.

adminRoleName

string

Discord role name that grants admin access.

matchTimeoutMinutes

number

Auto-expiry time for active matches.

Response

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

POST /api/admin/features/:key

Toggles a named feature flag. When a guildId is resolved, the flag is written to that guild’s Firestore settings document. Without a guildId, the global settings document is updated — this requires global_admin. Path Parameter

key

string

required

Feature flag key (e.g. autoWelcomeDm, liveMatchPanel, autoRoleSync).

Request Body

enabled

boolean

required

true to enable, false to disable.

Response

{ "success": true, "key": "liveMatchPanel", "enabled": true }

GET /api/admin/guilds

Returns all Discord guilds the bot is currently in. admin users only see their own guild. Response

{
  "guilds": [
    {
      "id": "987654321098765432",
      "name": "Mi Servidor",
      "icon": "https://cdn.discordapp.com/icons/...",
      "memberCount": 412
    }
  ]
}

GET /api/admin/guilds/:guildId/settings

Returns the effective per-guild configuration (global defaults merged with guild-specific overrides). Path Parameter

guildId

string

required

Guild ID. admin users can only access their own guild.

POST /api/admin/guilds/:guildId/settings

Saves per-guild settings to the guild_settings Firestore collection using merge semantics. Path Parameter

guildId

string

required

Guild ID. admin users can only update their own guild.

Request Body — partial or full guild settings object. Any keys present will be merged into the existing document. Response

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

Communication

GET /api/admin/messages

Returns the current message templates (welcome DM and support panel). Response

{
  "templates": {
    "welcomeTitle": "¡Bienvenido al Servidor! 🎉",
    "welcomeDescription": "...",
    "welcomeColor": "#FF5500",
    "supportTitle": "🚨 Soporte y Llamado de Admin",
    "supportDescription": "...",
    "supportColor": "#FF0000"
  }
}

POST /api/admin/messages

Saves updated message templates to Firestore. Requires global_admin role. Request Body — full templates object with the same keys as the GET response. Response

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

POST /api/admin/broadcast

Sends a direct message to all verified users in Firestore. Runs in the background at a rate of one DM per second. Requires global_admin role. Pass discordId to send to a single user instead. Request Body

message

string

required

Message text to send. Must not be empty.

discordId

string

If provided, sends only to this Discord user ID and returns immediately.

Response

{
  "success": true,
  "message": "Iniciando envío a 87 usuarios en segundo plano."
}

Support

GET /api/admin/support-calls

Returns the 50 most recent support call records, sorted by creation date descending. admin users only see calls for their guild. Response

{
  "calls": [
    {
      "id": "support-uuid",
      "faceit_nickname": "PlayerOne",
      "discord_id": "123456789012345678",
      "description": "Problema con la partida",
      "status": "pendiente",
      "match_url": "https://www.faceit.com/...",
      "guild_id": "987654321098765432"
    }
  ]
}

POST /api/admin/support-calls/:id/resolve

Marks a support call as resolved (atendida), sends a confirmation DM to the player, and attempts to delete the original alert message from the admin alerts channel. Path Parameter

string

required

Support call ID.

Response

{ "success": true }

Returns 404 if the call doesn’t exist, 400 if it’s already resolved, and 403 if an admin user tries to resolve a call from a different guild.

Logs & Monitoring

GET /api/admin/logs

Returns recent bot log entries from the faceit_bot_logs Firestore collection. Only error, warn, and system-sourced entries are persisted. Logs older than 7 days are pruned automatically. Query Parameters

limit

number

Maximum number of log entries to return. Defaults to 50.

Response

{
  "logs": [
    {
      "id": "log-doc-id",
      "level": "error",
      "message": "Error al obtener partidas activas",
      "source": "bot",
      "guild_id": null,
      "createdAt": { "_seconds": 1700000000 }
    }
  ]
}

POST /api/admin/panel/refresh

Forces an immediate update of the live match panel embed in the configured matches channel. Response

{ "success": true, "message": "Panel actualizado" }

Returns 400 if no matches channel is configured for the target guild.

POST /api/admin/simulate-webhook

Simulates a Faceit webhook event by passing the payload directly to the internal webhook handler. The response is returned immediately while the event is processed asynchronously. Requires global_admin role. Request Body The entire request body is passed directly to the internal webhook handler as the payload object. It should conform to the Faceit webhook schema, including a top-level event field.

event

string

required

Faceit webhook event name (e.g. "match_status_ready", "match_status_finished").

...

any

All other top-level fields of the Faceit webhook payload (e.g. payload, transaction_id, timestamp).

Response

{
  "success": true,
  "message": "Evento match_status_ready enviado al bot para procesamiento."
}

Discord Commands

REST API

Configuration

Documentation Index

​Guild Targeting

​System

​GET /api/admin/me

​GET /api/admin/system

​GET /api/admin/status

​GET /health

​Users

​GET /api/admin/users

​POST /api/admin/users/verify

​POST /api/admin/users/:id/unlink

​POST /api/admin/users/sync-all

​GET /api/admin/users/backup

​POST /api/admin/users/restore

​POST /api/admin/users/:id/roles

​POST /api/admin/users/:id/admin-role

​Matches

​GET /api/admin/matches

​POST /api/admin/matches/:id/cleanup

​GET /api/admin/matches/history

​Leaderboard & Stats

​GET /api/admin/leaderboard

​GET /api/admin/stats/:nickname

​Settings & Features

​GET /api/admin/settings

​POST /api/admin/settings

​POST /api/admin/features/:key

​GET /api/admin/guilds

​GET /api/admin/guilds/:guildId/settings

​POST /api/admin/guilds/:guildId/settings

​Communication

​GET /api/admin/messages

​POST /api/admin/messages

​POST /api/admin/broadcast

​Support

​GET /api/admin/support-calls

​POST /api/admin/support-calls/:id/resolve

​Logs & Monitoring

​GET /api/admin/logs

​POST /api/admin/panel/refresh

​POST /api/admin/simulate-webhook

Build docs developers (and LLMs) love

Guild Targeting

System

GET /api/admin/me

GET /api/admin/system

GET /api/admin/status

GET /health

Users

GET /api/admin/users

POST /api/admin/users/verify

POST /api/admin/users/:id/unlink

POST /api/admin/users/sync-all

GET /api/admin/users/backup

POST /api/admin/users/restore

POST /api/admin/users/:id/roles

POST /api/admin/users/:id/admin-role

Matches

GET /api/admin/matches

POST /api/admin/matches/:id/cleanup

GET /api/admin/matches/history

Leaderboard & Stats

GET /api/admin/leaderboard

GET /api/admin/stats/:nickname

Settings & Features

GET /api/admin/settings

POST /api/admin/settings

POST /api/admin/features/:key

GET /api/admin/guilds

GET /api/admin/guilds/:guildId/settings

POST /api/admin/guilds/:guildId/settings

Communication

GET /api/admin/messages

POST /api/admin/messages

POST /api/admin/broadcast

Support

GET /api/admin/support-calls

POST /api/admin/support-calls/:id/resolve

Logs & Monitoring

GET /api/admin/logs

POST /api/admin/panel/refresh

POST /api/admin/simulate-webhook