LuawardDocs

API и MCP для Discord

Читайте и меняйте панель, шаблоны, языки и профиль бота сервера через REST API, SDK и инструменты MCP с проверкой ревизий, чтобы ничего не перезаписалось случайно.

Всё, что делает страница сервера Discord, можно сделать и из кода: получить список серверов, прочитать действующую конфигурацию сервера, сохранить только изменённые части, поделиться шаблоном, опубликовать панель и применить профиль бота. Правила те же, что в панели управления: только серверы и картинки вашего рабочего пространства, ограничения тарифа Free на имя, картинку и подвал бота и проверка ревизии при каждом изменении.

Что нужно

ЧтениеЛюбой ключ Developer API.
ИзменениеКлюч с правом integrations:write (Full access его включает). Без него: 403 INSUFFICIENT_SCOPE.
ШаблоныКлюч на всё рабочее пространство. Ключ, ограниченный несколькими проектами, видит только серверы этих проектов и на шаблонах отвечает 403 DISCORD_WORKSPACE_ACCESS_REQUIRED.
Размер телаДо 128 КиБ.

Маршруты

Все маршруты находятся под https://api.luaward.com/v3 и отвечают { "success": true, "data": … }.

Метод и путьЧто делает
GET /discord/schemaТекущая схема конфигурации. Прочитайте её, прежде чем собирать тело запроса.
GET /discord/guildsПодключённые серверы с проектом, шаблоном и ревизией.
GET /discord/guilds/{guildId}/configДействующая конфигурация, собственные изменения сервера, шаблон, которому он следует, что разрешает тариф и устарело ли опубликованное сообщение.
PATCH /discord/guilds/{guildId}/configСохранить собственные изменения. Тело: expectedRevision, expectedPresetRevision, overrides.
POST /discord/guilds/{guildId}/config/resetОтбросить собственные изменения, чтобы сервер снова следовал шаблону. Тело: обе ревизии и paths.
PUT /discord/guilds/{guildId}/presetПривязать шаблон или null, чтобы отвязать. Тело: presetId, expectedRevision, preserveOverrides.
GET /discord/presets, GET /discord/presets/{id}Список шаблонов или один шаблон с его spec.
POST /discord/presetsСоздать шаблон: name и spec.
PATCH /discord/presets/{id}Заменить шаблон: name, spec, expectedRevision. Серверы, которые ему следуют, меняются вместе с ним.
DELETE /discord/presets/{id}Удалить шаблон: expectedRevision. Серверы, которые его использовали, сохраняют текущий вид.
POST /discordОдна точка входа для всех операций с полем op (её используют SDK), включая panel.publish и profile.apply.

Собственное изменение это плоский путь, например title, color, buttons, locales, redeemModal, show.guide или bot.nick. Списки и разделы языков и формы заменяются целиком; путь, который вы не передали, продолжает следовать шаблону, а null или пустой список очищает его.

Правила

Правила сервера это ещё три override, каждый заменяется целиком: rules.script, rules.redeem и 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 или both; scripts это "all" или список id скриптов проекта сервера; universes это список до 10 id Loader Universe рабочего пространства (для режима universe нужен хотя бы один).
  • rules.redeem: maxKeys от 1 до 10 или null без ограничения. Ключи с истёкшим сроком и заблокированные не считаются.
  • rules.reset: allowed и cooldownDays равны null, чтобы следовать проекту; maxPerKey и maxPer30Days равны null без ограничения; confirm сначала спрашивает игрока, с warning (до 300 символов) или встроенным предупреждением.

Изменение только правил не делает опубликованную панель устаревшей.

Ревизии

У каждого сервера есть ревизия конфигурации, и у каждого шаблона есть своя. Изменение должно передавать ревизию, на которой оно основано. Если кто-то изменил раньше, вызов отвечает 409 DISCORD_CONFIG_CONFLICT и ничего не меняет; прочитайте конфигурацию заново и повторите. Именно это не даёт двум людям, или скрипту и панели управления, перезаписать друг друга.

Публикация

panel.publish публикует новое сообщение (mode: "post" с channelId) или правит уже опубликованное (mode: "update"). Передавайте стабильный requestId и используйте его снова при повторе того же намерения: уже выполненный запрос не выполняется дважды. Перевод опубликованного embed в Components V2 требует confirmConvertToV2: true, а опубликованное сообщение V2 нельзя вернуть в embed (опубликуйте новое сообщение). profile.apply отправляет в Discord имя, картинку, баннер и текст о боте для одного сервера.

Ошибки, которые вы можете увидеть

КодЗначение
409 DISCORD_CONFIG_CONFLICTПереданная ревизия устарела.
403 DISCORD_BRANDING_PAIDИзменение задаёт имя или картинку бота либо подвал на тарифе Free.
404 GUILD_NOT_FOUND, PRESET_NOT_FOUND, IMAGE_NOT_FOUNDСервера, шаблона или картинки нет в вашем рабочем пространстве.
403 DISCORD_PRESET_LIMITРабочее пространство хранит не более 100 шаблонов.
409 DISCORD_OPERATION_BUSYДругое изменение этого сервера ещё выполняется. Повторите через минуту.
409 DISCORD_PUBLICATION_UNCERTAINDiscord не подтвердил публикацию. Проверьте канал, прежде чем повторять новым запросом.
404 DISCORD_RULES_UNIVERSE_NOT_FOUND, DISCORD_RULES_SCRIPT_NOT_FOUNDLoader Universe нет в вашем рабочем пространстве или скрипта нет в проекте сервера.
400 DISCORD_RULES_UNIVERSE_REQUIREDДля режима universe нужен хотя бы один Loader Universe.

SDK

SDK для JavaScript и Python оборачивают POST /discord. Записи они сами не повторяют.

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 },
});

Доступные функции: listGuilds, getConfiguration, saveConfiguration, resetOverrides, attachPreset, listPresets, getPreset, createPreset, updatePreset, deletePreset, publish, applyProfile и schema. Установка и учётные данные описаны в разделе SDK и CLI.

Инструменты MCP

ИИ-ассистент, подключённый к Luaward, получает два инструмента. discord_read показывает список серверов и шаблонов, читает конфигурацию сервера и возвращает схему (guilds.list, config.get, presets.list, presets.get, schema.get). discord_write сохраняет и сбрасывает собственные изменения, управляет шаблонами, привязывает шаблон, публикует панель и применяет профиль бота с теми же проверками, что и панель управления. Попросите ассистента сначала прочитать конфигурацию, а затем менять её с полученными ревизиями. Для обоих нужно право manage у личного токена, подключённая игра не требуется.