API y MCP de Discord
Lee y cambia el panel, las plantillas, los idiomas y el perfil del bot de un servidor desde la API REST, los SDK y las herramientas MCP, con comprobación de revisiones para que nada se sobrescriba por accidente.
Todo lo que hace la página del servidor de Discord también se puede hacer desde código: listar tus servidores, leer la configuración efectiva de un servidor, guardar solo las partes que cambiaste, compartir una plantilla, publicar el panel y aplicar el perfil del bot. Las reglas son las del panel de control: solo los servidores y las imágenes de tu propio espacio de trabajo, los límites del plan Free sobre el nombre, la imagen y el pie del bot, y una comprobación de revisión en cada cambio.
Qué necesitas
| Leer | Cualquier clave de la API para desarrolladores. |
| Cambiar | Una clave con el permiso integrations:write (Full access lo incluye). Sin él: 403 INSUFFICIENT_SCOPE. |
| Plantillas | Una clave de todo el espacio de trabajo. Una clave limitada a algunos proyectos solo llega a los servidores de esos proyectos y responde 403 DISCORD_WORKSPACE_ACCESS_REQUIRED con las plantillas. |
| Tamaño del cuerpo | Hasta 128 KiB. |
Rutas
Todas las rutas cuelgan de https://api.luaward.com/v3 y responden { "success": true, "data": … }.
| Método y ruta | Qué hace |
|---|---|
GET /discord/schema | El esquema de configuración actual. Léelo antes de construir un cuerpo. |
GET /discord/guilds | Los servidores vinculados, con proyecto, plantilla y revisión. |
GET /discord/guilds/{guildId}/config | La configuración efectiva, los cambios propios del servidor, la plantilla que sigue, lo que permite el plan y si el mensaje publicado está desactualizado. |
PATCH /discord/guilds/{guildId}/config | Guarda cambios propios. Cuerpo: expectedRevision, expectedPresetRevision, overrides. |
POST /discord/guilds/{guildId}/config/reset | Descarta cambios propios para que el servidor vuelva a seguir su plantilla. Cuerpo: las dos revisiones y paths. |
PUT /discord/guilds/{guildId}/preset | Asocia una plantilla, o null para quitarla. Cuerpo: presetId, expectedRevision, preserveOverrides. |
GET /discord/presets, GET /discord/presets/{id} | Lista las plantillas, o lee una con su spec. |
POST /discord/presets | Crea una plantilla: name y spec. |
PATCH /discord/presets/{id} | Reemplaza una plantilla: name, spec, expectedRevision. Los servidores que la siguen cambian con ella. |
DELETE /discord/presets/{id} | Elimina una plantilla: expectedRevision. Los servidores que la usaban conservan su aspecto actual. |
POST /discord | Un único endpoint para todas las operaciones, con un campo op (lo usan los SDK), incluidas panel.publish y profile.apply. |
Un cambio propio es una ruta plana como title, color, buttons, locales, redeemModal, show.guide o bot.nick. Las listas y las secciones de idiomas y de formulario se reemplazan enteras; una ruta que omites sigue a la plantilla, y null o una lista vacía la borra.
Reglas
Las reglas de un servidor son tres overrides más, cada uno reemplazado como un todo: rules.script, rules.redeem y rules.reset.
{
"overrides": {
"rules.script": { "mode": "both", "scripts": "all", "universes": ["<loader universe id>"] },
"rules.redeem": { "maxKeys": 2 },
"rules.reset": { "allowed": null, "cooldownDays": 7, "maxPerKey": 5, "maxPer30Days": 2, "confirm": true, "warning": null }
}
}rules.script:modeesscripts,universeoboth;scriptses"all"o una lista de ids de scripts del proyecto del servidor;universeses una lista de hasta 10 ids de Loader Universe del espacio de trabajo (el modouniversenecesita al menos uno).rules.redeem:maxKeysva de 1 a 10, onullpara no tener límite. Las claves vencidas o bloqueadas no cuentan.rules.reset:allowedycooldownDayssonnullpara seguir al proyecto;maxPerKeyymaxPer30Dayssonnullpara no tener límite;confirmpregunta antes al jugador, conwarning(hasta 300 caracteres) o la advertencia integrada.
Cambiar solo las reglas no deja desactualizado el panel publicado.
Revisiones
Cada servidor tiene una revisión de configuración, y cada plantilla tiene la suya. Un cambio debe enviar la revisión en la que se basa. Si otra persona cambió antes, la llamada responde 409 DISCORD_CONFIG_CONFLICT y no cambia nada; vuelve a leer la configuración y reintenta. Así se evita que dos personas, o un script y el panel de control, se sobrescriban.
Publicación
panel.publish publica un mensaje nuevo (mode: "post" con un channelId) o edita el ya publicado (mode: "update"). Envía un requestId estable y reutilízalo al reintentar la misma intención: una solicitud que ya se llevó a cabo no se ejecuta dos veces. Convertir un embed publicado a Components V2 requiere confirmConvertToV2: true, y un mensaje V2 publicado no puede volver a ser un embed (publica un mensaje nuevo). profile.apply envía a Discord el nombre, la imagen, el banner y el texto "acerca de" del bot de un servidor.
Errores que puedes ver
| Código | Significado |
|---|---|
| 409 DISCORD_CONFIG_CONFLICT | La revisión que enviaste está desactualizada. |
| 403 DISCORD_BRANDING_PAID | El cambio fija el nombre o la imagen del bot o el pie en el plan Free. |
| 404 GUILD_NOT_FOUND, PRESET_NOT_FOUND, IMAGE_NOT_FOUND | El servidor, la plantilla o la imagen no están en tu espacio de trabajo. |
| 403 DISCORD_PRESET_LIMIT | Un espacio de trabajo guarda como máximo 100 plantillas. |
| 409 DISCORD_OPERATION_BUSY | Otro cambio en este servidor sigue en curso. Inténtalo en un momento. |
| 409 DISCORD_PUBLICATION_UNCERTAIN | Discord no confirmó la publicación. Revisa el canal antes de reintentar con una solicitud nueva. |
| 404 DISCORD_RULES_UNIVERSE_NOT_FOUND, DISCORD_RULES_SCRIPT_NOT_FOUND | Un Loader Universe no está en tu espacio de trabajo, o un script no está en el proyecto del servidor. |
| 400 DISCORD_RULES_UNIVERSE_REQUIRED | El modo universe necesita al menos un Loader Universe. |
SDK
Los SDK de JavaScript y Python envuelven POST /discord. No reintentan las escrituras por su cuenta.
import { LuawardClient } from "@luaward/sdk";
const luaward = new LuawardClient({ apiKey: process.env.LUAWARD_API_KEY });
const { data: guilds } = await luaward.discord.listGuilds();
const { data: config } = await luaward.discord.getConfiguration(guilds[0].guildId);
await luaward.discord.saveConfiguration({
guildId: config.guildId,
expectedRevision: config.revision,
expectedPresetRevision: config.preset?.revision ?? null,
overrides: { title: "My Hub keys", color: 0x23a559 },
});Las funciones son listGuilds, getConfiguration, saveConfiguration, resetOverrides, attachPreset, listPresets, getPreset, createPreset, updatePreset, deletePreset, publish, applyProfile y schema. Consulta SDK y CLI para la instalación y las credenciales.
Herramientas MCP
Un asistente de IA conectado a Luaward recibe dos herramientas. discord_read lista servidores y plantillas, lee la configuración de un servidor y devuelve el esquema (guilds.list, config.get, presets.list, presets.get, schema.get). discord_write guarda y restablece cambios propios, gestiona plantillas, asocia una plantilla, publica el panel y aplica el perfil del bot, con las mismas comprobaciones que el panel de control. Pide al asistente que lea primero la configuración y que la cambie después con las revisiones recibidas. Ambas necesitan el permiso manage en el token personal, y no hace falta un juego conectado.