Developer Resources

Build & Grow

DiscordForge is the perfect place to grow your bot's user base. We provide powerful tools and a dedicated community to help you succeed.

Adding a Bot

Adding your bot to DiscordForge is simple and takes less than 2 minutes.

Open the Menu and select Add.
Choose Bot from the submission options.
Fill in your Bot's details (Client ID, Prefix, Description, etc.).
Copy the verification code (e.g., df-verify-xyz) shown in the form and add it to your bot's About Me section on Discord.
Click Submit. Our system will verify the code and send your bot to the Review Queue.
Once a moderator approves it (checking for ToS compliance), your bot will be listed!

Announcements

Keep your users updated directly from your bot's profile page.

Visibility: Announcements appear at the top of your bot's profile, above the description.
Markdown: Full Markdown support including links, lists, and code blocks.
One at a time: Each new announcement overwrites the previous one, keeping information fresh.

Widgets

Show off your bot's status on your website or GitHub README.

Go to your bot's profile, click the Actions menu, and select Widget.

JSON / APIGet raw data for custom implementations.

HTML / MarkdownReady-to-use embed codes.

Project Management

Need to update your bot's description, prefix, or links?

Go to your Dashboard
Click "Edit" on your project card
Save changes instantly

Growth Tools

Forge Synergy

Link your bot to a "Perfect Match" partner project to cross-promote audiences.

API Access

We offer a robust REST API for posting stats and fetching bot data.

How to get your API Key

Go to Dashboard → My Bots.
Click on your bot's card to open its details.
Navigate to the API Access tab.
Click Generate or Regenerate to get your token.

POST /api/bots/stats

Update your bot's statistics. Rate limit: 1 request / 5 minutes.

Endpoint: https://discordforge.org/api/bots/stats

Headers:
Authorization: <YOUR_API_KEY> or x-api-key: <YOUR_API_KEY>
Content-Type: application/json

{ "server_count": 1500, "shard_count": 5, // Optional "user_count": 50000, // Optional "voice_connections": 10 // Optional }

GET /api/bots/:id/votes/check

Check if a user has voted in the last 12 hours. Rate limit: 60 requests / minute.

Endpoint: https://discordforge.org/api/bots/:id/votes/check?userId=...

Headers:
Authorization: <YOUR_API_KEY>

{ "hasVoted": true, "votedAt": "2023-10-27T10:00:00.000Z", "nextVoteAt": "2023-10-27T22:00:00.000Z" }

GET /api/bots/:id

Fetch public information about a bot. No authentication required.

Endpoint: https://discordforge.org/api/bots/:id

{ "id": "...", "name": "MyBot", "voteCount": 150, "serverCount": 100, ... }

POST /api/external/bots/commandsNEW

Sync your bot's slash commands to DiscordForge. This replaces all existing commands with the provided list. Max 200 commands per bot. Accepts both our custom format and the raw Discord API slash command format - auto-detected per command.

Endpoint: https://discordforge.org/api/external/bots/commands

Headers:
x-api-key: <YOUR_API_KEY> or Authorization: <YOUR_API_KEY>
Content-Type: application/json

Custom Format:

{ "commands": [ { "name": "ban", "description": "Ban a user from the server", "usage": "/ban @user [reason]", "category": "Moderation" }, { "name": "play", "description": "Play a song in your voice channel", "usage": "/play <song name or URL>", "category": "Music" } ] }

Discord API Format (auto-detected):

{ "commands": [ { "name": "ban", "description": "Ban a user from the server", "type": 1, "options": [ { "name": "user", "type": 6, "required": true }, { "name": "reason", "type": 3, "required": false } ] } ] }

Auto-mapping: Options are converted to a usage string automatically - required params become <name>, optional become [name]. Subcommands and subcommand groups are flattened into separate entries. Both formats can be mixed in a single request.

Response:

{ "success": true, "synced": 2 }

Integration Examples

Sync your registered slash commands on bot startup. The endpoint accepts up to 200 commands per request - all fields except name and description are optional.

Node.js

// Sync on ready - adapt to your framework const commands = client.application.commands.cache.map(cmd => ({ name: cmd.name, description: cmd.description, usage: cmd.options?.map(o => o.required ? `<${o.name}>` : `[${o.name}]`).join(" ") ?? null, category: "General" // or infer from your command structure });; await fetch("https://discordforge.org/api/external/bots/commands", { method: "POST", headers: { "Content-Type": "application/json", "x-api-key": process.env.DISCORDFORGE_API_KEY }, body: JSON.stringify({ commands: commands.slice(0, 200) }) });

Python

import requests, os commands = [{"name": c.name, "description": c.description} for c in bot.tree.get_commands()] requests.post( "https://discordforge.org/api/external/bots/commands", json={"commands": commands[:200]}, headers={"x-api-key": os.environ["DISCORDFORGE_API_KEY"]}, timeout=10 )

cURL

curl -X POST https://discordforge.org/api/external/bots/commands \ -H "Content-Type: application/json" \ -H "x-api-key: $DISCORDFORGE_API_KEY" \ -d '{"commands":[{"name":"ban","description":"Ban a user","category":"Moderation"}]}'

Command Object

Field	Type	Required	Description
name	string	✓	Slash command name (e.g. "ban")
description	string	✓	What the command does
usage	string?	-	Usage syntax (e.g. "/ban <user> [reason]")
category	string?	-	Grouping label (e.g. "Moderation", "Music")

Limits

Max 200 commands per sync. If your bot has more, send the most relevant ones. Skip subcommand variants.
Each sync replaces all previously synced commands. This is not a merge - it's a full overwrite.
Categories are freeform strings. Use whatever makes sense for your bot - they're displayed as filter tabs in the catalog.
Commands can also be managed manually via Dashboard → Slash Commands. No API key required.

Node.js SDK

The SDK wraps the same API described above into a single npm package. If you don't want to manage fetch calls and rate-limit headers yourself, this is the easier path.

Install

npm install discordforge-sdk

Requires Node.js 18+. Zero dependencies. TypeScript types included.

Manual posting

const { ForgeClient } = require("discordforge-sdk"); const forge = new ForgeClient("YOUR_API_KEY"); await forge.postStats({ serverCount: client.guilds.cache.size, shardCount: client.ws.shards.size, });

AutoPosterRECOMMENDED

const { ForgeClient, AutoPoster } = require("discordforge-sdk"); const forge = new ForgeClient("YOUR_API_KEY"); const poster = new AutoPoster(forge, client); poster.on("post", (stats) => console.log(`Posted: ${stats.serverCount} servers`)); poster.on("error", (err) => console.error(err));

Starts automatically on the Discord client's ready event. Posts every 5 minutes. Never crashes your bot if the API is down.

Available Methods

Method	Rate Limit	Description
postStats(stats)	1 req / 5 min	Post server / shard / user count
checkVote(userId)	60 req / min	Check if a user voted in the last 12 h (needs botId)
getBot()	-	Fetch bot profile info (needs botId)
syncCommands(cmds)	-	Sync up to 200 commands - same endpoint as above

botId is optional in the constructor. Only checkVote() and getBot() need it. postStats() and syncCommands() work with just an API key.

npm GitHub

Automatic Bot Status

DiscordForge automatically detects whether your bot is online, idle, DND, or offline. No setup required - if your bot shares a server with the DiscordForge bot, its status indicator will update automatically every 5 minutes.

Online

Bot is active and responding

Idle

Bot is online but inactive

Do Not Disturb

Bot is in DND mode

Vanity URLs

FORGE subscribers can set a custom vanity URL for their bot's profile page, making it easier to share and remember.

FORGE EXCLUSIVE

https://discordforge.org/bot/your-custom-slug

3-32 characters, lowercase letters, numbers, and hyphens
Configure it in Dashboard → Bot Settings → Vanity URL
Automatically revoked if FORGE subscription expires

Webhooks

Vote webhooks are fired whenever a user upvotes your bot. This can be configured in your bot editing settings via the Dashboard. It is advised to implement vote webhooks in your bot so you can reward users the moment they vote, which encourages them to keep coming back and voting again.

POST https://your-api.com/your-webhook-url

This request is made to your API when an upvote is made.

Headers

Name	Type	Description
Authorization	string	The webhook secret you configured

Request Body

Name	Type	Description
admin	boolean	If the user is a site administrator
avatar	string	The avatar hash/URL of the user
username	string	The username of the user who voted
id	string	The Discord ID of the user who voted
weeklyVotes	number	Number of votes this bot has received this week
totalVotes	number	Total lifetime votes count for your bot
isTest	boolean	If `true`, this is a test webhook sent from the Dashboard - not a real vote

You can easily listen for these webhooks using Express.js:

const express = require("express"); const app = express(); app.use(express.json()); app.post("/forge-webhook", (req, res) => { const auth = req.headers.authorization; if (auth !== "your webhook auth secret") { return res.status(401).send("Unauthorized"); } const vote = req.body; console.log(vote.id); // User who voted console.log(vote.username); // Their username console.log(vote.weeklyVotes); // Bot\'s weekly vote count res.status(200).send("OK"); }); app.listen(80);

Vote Notifications

Get real-time Discord notifications whenever someone votes for your bot or server. No coding required.

Zero-Code Setup

Unlike webhooks, vote notifications are sent directly to your Discord server by the Forge bot. No server infrastructure needed.

Setup via Dashboard

Go to Dashboard → Integrations.
Click Configure on your bot or server.
Select a notification channel and customize your message.
Optionally enable Vote Role Rewards to auto-assign roles.
Click Send Test to verify everything works.

Setup via Discord Command

Make sure the Forge bot is in your server.
Run /integration setup and select your bot or server.
Choose a channel and optionally a reward role.
Select message type (plain text or embed) and customize.
Hit Send Test to confirm.

Available Placeholders

Use these in your notification message:

{username}Voter's name

{user.id}Voter's Discord ID

{bot.name}Bot name

{server.name}Server name

{votes.total}Total votes

{votes.monthly}Monthly votes

{votes.weekly}Weekly votes

{streak}Vote streak

Vote Role Rewards

Automatically assign a Discord role to users who vote. The role is granted instantly when a vote is registered.

Set a vote threshold (e.g., assign role after 5 votes).
The Forge bot needs Manage Roles permission.
The reward role must be below the Forge bot's highest role.

Getting Started

Platform Functions

Badges & Achievements

For Developers

Server Owners

Billing & Premium

Verification