API e MCP do Discord
Leia e altere o painel, os modelos, os idiomas e o perfil do bot de um servidor pela API REST, pelos SDKs e pelas ferramentas MCP, com verificação de revisões para que nada seja sobrescrito por acidente.
Tudo o que a página do servidor do Discord faz também pode ser feito por código: listar seus servidores, ler a configuração efetiva de um servidor, salvar só as partes que você alterou, compartilhar um modelo, publicar o painel e aplicar o perfil do bot. As regras são as do painel de controle: somente os servidores e as imagens do seu próprio espaço de trabalho, os limites do plano Free para o nome, a imagem e o rodapé do bot, e uma verificação de revisão em cada alteração.
O que você precisa
| Ler | Qualquer chave da API para desenvolvedores. |
| Alterar | Uma chave com o escopo integrations:write (Full access o inclui). Sem ele: 403 INSUFFICIENT_SCOPE. |
| Modelos | Uma chave de todo o espaço de trabalho. Uma chave limitada a alguns projetos alcança só os servidores desses projetos e responde 403 DISCORD_WORKSPACE_ACCESS_REQUIRED nos modelos. |
| Tamanho do corpo | Até 128 KiB. |
Rotas
Todas as rotas ficam em https://api.luaward.com/v3 e respondem { "success": true, "data": … }.
| Método e caminho | O que faz |
|---|---|
GET /discord/schema | O esquema de configuração atual. Leia antes de montar um corpo. |
GET /discord/guilds | Os servidores vinculados, com projeto, modelo e revisão. |
GET /discord/guilds/{guildId}/config | A configuração efetiva, as alterações próprias do servidor, o modelo que ele segue, o que o plano permite e se a mensagem publicada está desatualizada. |
PATCH /discord/guilds/{guildId}/config | Salva alterações próprias. Corpo: expectedRevision, expectedPresetRevision, overrides. |
POST /discord/guilds/{guildId}/config/reset | Descarta alterações próprias para o servidor voltar a seguir o modelo. Corpo: as duas revisões e paths. |
PUT /discord/guilds/{guildId}/preset | Associa um modelo, ou null para soltar. Corpo: presetId, expectedRevision, preserveOverrides. |
GET /discord/presets, GET /discord/presets/{id} | Lista os modelos, ou lê um com o seu spec. |
POST /discord/presets | Cria um modelo: name e spec. |
PATCH /discord/presets/{id} | Substitui um modelo: name, spec, expectedRevision. Os servidores que o seguem mudam junto. |
DELETE /discord/presets/{id} | Exclui um modelo: expectedRevision. Os servidores que o usavam mantêm o visual atual. |
POST /discord | Um único endpoint para todas as operações, com um campo op (os SDKs o usam), incluindo panel.publish e profile.apply. |
Uma alteração própria é um caminho plano como title, color, buttons, locales, redeemModal, show.guide ou bot.nick. As listas e as seções de idiomas e de formulário são substituídas por inteiro; um caminho que você omite continua seguindo o modelo, e null ou uma lista vazia o limpa.
Regras
As regras de um servidor são mais três overrides, cada um substituído por inteiro: rules.script, rules.redeem e 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:modeéscripts,universeouboth;scriptsé"all"ou uma lista de ids de scripts do projeto do servidor;universesé uma lista de até 10 ids de Loader Universe do espaço de trabalho (o modouniverseprecisa de pelo menos um).rules.redeem:maxKeysvai de 1 a 10, ounullpara sem limite. Chaves encerradas ou banidas não contam.rules.reset:allowedecooldownDayssãonullpara seguir o projeto;maxPerKeyemaxPer30Dayssãonullpara sem limite;confirmpergunta antes ao jogador, comwarning(até 300 caracteres) ou o aviso padrão.
Alterar só as regras não deixa o painel publicado desatualizado.
Revisões
Cada servidor tem uma revisão de configuração, e cada modelo tem a sua. Uma alteração deve enviar a revisão em que se baseia. Se outra pessoa alterou antes, a chamada responde 409 DISCORD_CONFIG_CONFLICT e não muda nada; leia a configuração de novo e tente outra vez. É isso que impede que duas pessoas, ou um script e o painel de controle, sobrescrevam uma à outra.
Publicação
panel.publish publica uma mensagem nova (mode: "post" com um channelId) ou edita a já publicada (mode: "update"). Envie um requestId estável e reutilize-o ao repetir a mesma intenção: uma solicitação que já foi executada não é executada duas vezes. Converter um embed publicado para Components V2 exige confirmConvertToV2: true, e uma mensagem V2 publicada não volta a ser embed (publique uma mensagem nova). profile.apply envia ao Discord o nome, a imagem, o banner e o texto sobre o bot de um servidor.
Erros que você pode ver
| Código | Significado |
|---|---|
| 409 DISCORD_CONFIG_CONFLICT | A revisão enviada está desatualizada. |
| 403 DISCORD_BRANDING_PAID | A alteração define o nome ou a imagem do bot ou o rodapé no plano Free. |
| 404 GUILD_NOT_FOUND, PRESET_NOT_FOUND, IMAGE_NOT_FOUND | O servidor, o modelo ou a imagem não está no seu espaço de trabalho. |
| 403 DISCORD_PRESET_LIMIT | Um espaço de trabalho guarda no máximo 100 modelos. |
| 409 DISCORD_OPERATION_BUSY | Outra alteração neste servidor ainda está em andamento. Tente de novo em instantes. |
| 409 DISCORD_PUBLICATION_UNCERTAIN | O Discord não confirmou a publicação. Confira o canal antes de tentar de novo com uma solicitação nova. |
| 404 DISCORD_RULES_UNIVERSE_NOT_FOUND, DISCORD_RULES_SCRIPT_NOT_FOUND | Um Loader Universe não está no seu espaço de trabalho, ou um script não está no projeto do servidor. |
| 400 DISCORD_RULES_UNIVERSE_REQUIRED | O modo universe precisa de pelo menos um Loader Universe. |
SDKs
Os SDKs de JavaScript e Python envolvem POST /discord. Eles não repetem as gravações por conta própria.
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 },
});As funções são listGuilds, getConfiguration, saveConfiguration, resetOverrides, attachPreset, listPresets, getPreset, createPreset, updatePreset, deletePreset, publish, applyProfile e schema. Veja SDKs e CLI para a instalação e as credenciais.
Ferramentas MCP
Um assistente de IA conectado à Luaward recebe duas ferramentas. discord_read lista servidores e modelos, lê a configuração de um servidor e devolve o esquema (guilds.list, config.get, presets.list, presets.get, schema.get). discord_write salva e redefine alterações próprias, gerencia modelos, associa um modelo, publica o painel e aplica o perfil do bot, com as mesmas verificações do painel de controle. Peça ao assistente que leia primeiro a configuração e a altere depois com as revisões recebidas. Ambas exigem o escopo manage no token pessoal, e não é preciso um jogo conectado.