API dan MCP Discord
Baca dan ubah panel, preset, bahasa, dan profil bot sebuah server lewat REST API, SDK, dan alat MCP, dengan pemeriksaan revisi agar tidak ada yang tertimpa tanpa sengaja.
Semua yang bisa dilakukan halaman server Discord juga bisa dilakukan lewat kode: menampilkan daftar server, membaca konfigurasi efektif sebuah server, menyimpan bagian yang Anda ubah, membagikan preset, memposting panel, dan menerapkan profil bot. Aturannya sama dengan dasbor: hanya server dan gambar milik workspace Anda sendiri, batasan paket Free untuk nama, gambar, dan footer bot, serta pemeriksaan revisi pada setiap perubahan.
Yang Anda perlukan
| Membaca | Developer API key apa pun. |
| Mengubah | Key dengan scope integrations:write (Full access sudah mencakupnya). Tanpa itu: 403 INSUFFICIENT_SCOPE. |
| Preset | Key untuk seluruh workspace. Key yang dibatasi pada beberapa proyek hanya menjangkau server milik proyek itu dan menjawab 403 DISCORD_WORKSPACE_ACCESS_REQUIRED untuk preset. |
| Ukuran body | Hingga 128 KiB. |
Rute
Semua rute berada di bawah https://api.luaward.com/v3 dan menjawab { "success": true, "data": … }.
| Metode dan path | Fungsi |
|---|---|
GET /discord/schema | Skema konfigurasi saat ini. Baca sebelum menyusun body. |
GET /discord/guilds | Server yang tertaut, dengan proyek, preset, dan revisi. |
GET /discord/guilds/{guildId}/config | Konfigurasi efektif, perubahan milik server, preset yang diikuti, yang diizinkan paket, dan apakah pesan yang diposting sudah usang. |
PATCH /discord/guilds/{guildId}/config | Simpan perubahan milik server. Body: expectedRevision, expectedPresetRevision, overrides. |
POST /discord/guilds/{guildId}/config/reset | Buang perubahan milik server agar server kembali mengikuti preset. Body: kedua revisi dan paths. |
PUT /discord/guilds/{guildId}/preset | Pasang preset, atau null untuk melepas. Body: presetId, expectedRevision, preserveOverrides. |
GET /discord/presets, GET /discord/presets/{id} | Tampilkan daftar preset, atau baca satu beserta spec-nya. |
POST /discord/presets | Buat preset: name dan spec. |
PATCH /discord/presets/{id} | Ganti preset: name, spec, expectedRevision. Server yang mengikutinya ikut berubah. |
DELETE /discord/presets/{id} | Hapus preset: expectedRevision. Server yang memakainya mempertahankan tampilan saat ini. |
POST /discord | Satu endpoint untuk semua operasi, dengan field op (dipakai SDK), termasuk panel.publish dan profile.apply. |
Perubahan milik server adalah path datar seperti title, color, buttons, locales, redeemModal, show.guide, atau bot.nick. Daftar serta bagian bahasa dan formulir diganti seluruhnya; path yang tidak Anda kirim tetap mengikuti preset, dan null atau daftar kosong menghapusnya.
Aturan
Aturan sebuah server adalah tiga override tambahan, masing-masing diganti sebagai satu kesatuan: rules.script, rules.redeem, dan 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:modeadalahscripts,universe, atauboth;scriptsadalah"all"atau daftar id skrip proyek server;universesadalah daftar hingga 10 id Loader Universe di workspace (modeuniversemembutuhkan minimal satu).rules.redeem:maxKeysbernilai 1 sampai 10, ataunulluntuk tanpa batas. Kunci yang sudah berakhir atau diblokir tidak dihitung.rules.reset:alloweddancooldownDaysbernilainulluntuk mengikuti proyek;maxPerKeydanmaxPer30Daysbernilainulluntuk tanpa batas;confirmmenanyai pemain dulu, denganwarning(maksimal 300 karakter) atau peringatan bawaan.
Mengubah aturan saja tidak membuat panel yang sudah diposting menjadi usang.
Revisi
Setiap server punya revisi konfigurasi, dan setiap preset punya revisinya sendiri. Perubahan harus mengirim revisi yang menjadi dasarnya. Jika orang lain mengubah lebih dulu, panggilan dijawab 409 DISCORD_CONFIG_CONFLICT dan tidak mengubah apa pun; baca konfigurasi lagi lalu coba ulang. Inilah yang mencegah dua orang, atau skrip dan dasbor, saling menimpa.
Memposting
panel.publish memposting pesan baru (mode: "post" dengan channelId) atau mengedit yang sudah diposting (mode: "update"). Kirim requestId yang stabil dan pakai lagi saat mencoba ulang maksud yang sama: permintaan yang sudah dijalankan tidak dijalankan dua kali. Mengubah embed yang sudah diposting ke Components V2 memerlukan confirmConvertToV2: true, dan pesan V2 yang sudah diposting tidak bisa kembali menjadi embed (posting pesan baru). profile.apply mengirim nama, gambar, banner, dan teks tentang bot milik satu server ke Discord.
Kesalahan yang mungkin Anda lihat
| Kode | Arti |
|---|---|
| 409 DISCORD_CONFIG_CONFLICT | Revisi yang Anda kirim sudah usang. |
| 403 DISCORD_BRANDING_PAID | Perubahan mengatur nama atau gambar bot atau footer di paket Free. |
| 404 GUILD_NOT_FOUND, PRESET_NOT_FOUND, IMAGE_NOT_FOUND | Server, preset, atau gambar tidak ada di workspace Anda. |
| 403 DISCORD_PRESET_LIMIT | Sebuah workspace menyimpan paling banyak 100 preset. |
| 409 DISCORD_OPERATION_BUSY | Perubahan lain pada server ini masih berjalan. Coba lagi sebentar. |
| 409 DISCORD_PUBLICATION_UNCERTAIN | Discord tidak mengonfirmasi posting. Periksa saluran sebelum mencoba lagi dengan permintaan baru. |
| 404 DISCORD_RULES_UNIVERSE_NOT_FOUND, DISCORD_RULES_SCRIPT_NOT_FOUND | Sebuah Loader Universe tidak ada di workspace Anda, atau sebuah skrip tidak ada di proyek server. |
| 400 DISCORD_RULES_UNIVERSE_REQUIRED | Mode universe membutuhkan minimal satu Loader Universe. |
SDK
SDK JavaScript dan Python membungkus POST /discord. Keduanya tidak mencoba ulang penulisan dengan sendirinya.
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 },
});Fungsinya adalah listGuilds, getConfiguration, saveConfiguration, resetOverrides, attachPreset, listPresets, getPreset, createPreset, updatePreset, deletePreset, publish, applyProfile, dan schema. Lihat SDK dan CLI untuk instalasi dan kredensial.
Alat MCP
Asisten AI yang terhubung ke Luaward mendapat dua alat. discord_read menampilkan daftar server dan preset, membaca konfigurasi sebuah server, dan mengembalikan skema (guilds.list, config.get, presets.list, presets.get, schema.get). discord_write menyimpan dan mereset perubahan milik server, mengelola preset, memasang preset, memposting panel, dan menerapkan profil bot, dengan pemeriksaan yang sama seperti dasbor. Minta asisten membaca konfigurasi lebih dulu, lalu mengubahnya dengan revisi yang diterimanya. Keduanya memerlukan scope manage pada personal token, dan tidak memerlukan game yang terhubung.