Discord API and MCP
Read and change a server's panel, presets, languages and bot profile from the REST API, the SDKs and the MCP tools, with revision checks so nothing is overwritten by accident.
Everything the Discord server page does can be done from code: list your servers, read a server's effective configuration, save the parts you changed, share a preset, publish the panel and apply the bot's profile. The rules are the same as in the dashboard: only your own workspace's servers and pictures, the Free plan's limits on the bot's name, picture and footer, and a revision check on every change.
What you need
| Read | Any Developer API key. |
| Change | A key with the integrations:write scope (Full access includes it). Without it: 403 INSUFFICIENT_SCOPE. |
| Presets | A key for the whole workspace. A key limited to some projects reaches only the servers of those projects and answers 403 DISCORD_WORKSPACE_ACCESS_REQUIRED for presets. |
| Body size | Up to 128 KiB. |
Routes
All routes are under https://api.luaward.com/v3 and answer { "success": true, "data": … }.
| Method and path | What it does |
|---|---|
GET /discord/schema | The current configuration schema. Read it before you build a body. |
GET /discord/guilds | The linked servers, with project, preset and revision. |
GET /discord/guilds/{guildId}/config | The effective configuration, the server's own overrides, the preset it follows, what the plan allows and whether the posted message is out of date. |
PATCH /discord/guilds/{guildId}/config | Save overrides. Body: expectedRevision, expectedPresetRevision, overrides. |
POST /discord/guilds/{guildId}/config/reset | Drop overrides so the server follows its preset again. Body: the two revisions and paths. |
PUT /discord/guilds/{guildId}/preset | Attach a preset, or null to detach. Body: presetId, expectedRevision, preserveOverrides. |
GET /discord/presets, GET /discord/presets/{id} | List presets, or read one with its spec. |
POST /discord/presets | Create a preset: name and spec. |
PATCH /discord/presets/{id} | Replace a preset: name, spec, expectedRevision. Servers that follow it change with it. |
DELETE /discord/presets/{id} | Delete a preset: expectedRevision. Servers that used it keep their current look. |
POST /discord | One endpoint for every operation, with an op field (the SDKs use it), including panel.publish and profile.apply. |
An override is a flat path such as title, color, buttons, locales, redeemModal, show.guide or bot.nick. Lists and the language and form sections are replaced as a whole; a path you leave out keeps following the preset, and null or an empty list clears it.
Rules
A server's rules are three more overrides, each replaced as a whole: rules.script, rules.redeem and 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:modeisscripts,universeorboth;scriptsis"all"or a list of script ids of the server's project;universesis a list of up to 10 Loader Universe ids of the workspace (theuniversemode needs at least one).rules.redeem:maxKeysis 1 to 10, ornullfor no limit. Keys that ended or were banned do not count.rules.reset:allowedandcooldownDaysarenullto follow the project;maxPerKeyandmaxPer30Daysarenullfor no limit;confirmasks the player first, withwarning(up to 300 characters) or the built-in warning.
Changing only rules does not make the posted panel out of date.
Revisions
Every server has a configuration revision, and every preset has its own. A change must send the revision it was based on. If someone else changed it first, the call answers 409 DISCORD_CONFIG_CONFLICT and changes nothing; read the configuration again and retry. This is what stops two people, or a script and the dashboard, from overwriting each other.
Publishing
panel.publish posts a new message (mode: "post" with a channelId) or edits the one already posted (mode: "update"). Send a stable requestId and reuse it when you retry the same intent: a request that was already carried out is not carried out twice. Turning a posted embed into Components V2 needs confirmConvertToV2: true, and a posted V2 message cannot become an embed again (post a new message). profile.apply sends the bot's name, picture, banner and about text to Discord for one server.
Errors you may see
| Code | Meaning |
|---|---|
| 409 DISCORD_CONFIG_CONFLICT | The revision you sent is out of date. |
| 403 DISCORD_BRANDING_PAID | The change sets the bot's name or picture or the footer on the Free plan. |
| 404 GUILD_NOT_FOUND, PRESET_NOT_FOUND, IMAGE_NOT_FOUND | The server, preset or picture is not in your workspace. |
| 403 DISCORD_PRESET_LIMIT | A workspace keeps at most 100 presets. |
| 409 DISCORD_OPERATION_BUSY | Another change to this server is still running. Try again shortly. |
| 409 DISCORD_PUBLICATION_UNCERTAIN | Discord did not confirm the post. Check the channel before you retry with a new request. |
| 404 DISCORD_RULES_UNIVERSE_NOT_FOUND, DISCORD_RULES_SCRIPT_NOT_FOUND | A Loader Universe is not in your workspace, or a script is not in the server's project. |
| 400 DISCORD_RULES_UNIVERSE_REQUIRED | The universe mode needs at least one Loader Universe. |
SDKs
The JavaScript and Python SDKs wrap POST /discord. They do not retry writes on their own.
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 },
});The helpers are listGuilds, getConfiguration, saveConfiguration, resetOverrides, attachPreset, listPresets, getPreset, createPreset, updatePreset, deletePreset, publish, applyProfile and schema. See SDKs and CLI for installing and credentials.
MCP tools
An AI assistant connected to Luaward gets two tools. discord_read lists servers and presets, reads a server's configuration and returns the schema (guilds.list, config.get, presets.list, presets.get, schema.get). discord_write saves and resets overrides, manages presets, attaches a preset, publishes the panel and applies the bot's profile, with the same checks as the dashboard. Ask the assistant to read the configuration first, then change it with the revisions it was given. Both need the manage scope on the personal token, and no connected game.