LuawardDocs

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

LerQualquer chave da API para desenvolvedores.
AlterarUma chave com o escopo integrations:write (Full access o inclui). Sem ele: 403 INSUFFICIENT_SCOPE.
ModelosUma 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 corpoAté 128 KiB.

Rotas

Todas as rotas ficam em https://api.luaward.com/v3 e respondem { "success": true, "data": … }.

Método e caminhoO que faz
GET /discord/schemaO esquema de configuração atual. Leia antes de montar um corpo.
GET /discord/guildsOs servidores vinculados, com projeto, modelo e revisão.
GET /discord/guilds/{guildId}/configA 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}/configSalva alterações próprias. Corpo: expectedRevision, expectedPresetRevision, overrides.
POST /discord/guilds/{guildId}/config/resetDescarta alterações próprias para o servidor voltar a seguir o modelo. Corpo: as duas revisões e paths.
PUT /discord/guilds/{guildId}/presetAssocia 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/presetsCria 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 /discordUm ú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, universe ou both; 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 modo universe precisa de pelo menos um).
  • rules.redeem: maxKeys vai de 1 a 10, ou null para sem limite. Chaves encerradas ou banidas não contam.
  • rules.reset: allowed e cooldownDays são null para seguir o projeto; maxPerKey e maxPer30Days são null para sem limite; confirm pergunta antes ao jogador, com warning (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ódigoSignificado
409 DISCORD_CONFIG_CONFLICTA revisão enviada está desatualizada.
403 DISCORD_BRANDING_PAIDA 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_FOUNDO servidor, o modelo ou a imagem não está no seu espaço de trabalho.
403 DISCORD_PRESET_LIMITUm espaço de trabalho guarda no máximo 100 modelos.
409 DISCORD_OPERATION_BUSYOutra alteração neste servidor ainda está em andamento. Tente de novo em instantes.
409 DISCORD_PUBLICATION_UNCERTAINO 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_FOUNDUm 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_REQUIREDO 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.