canonical: https://jentic.com/apis/discord.com/discord

# Discord HTTP API (Preview)

The Discord HTTP API powers bots, integrations, and applications across Discord servers (guilds), channels, voice connections, and user accounts. The v10 surface covers 217 endpoints spanning guilds, channels, messages, threads, members, roles, voice regions, OAuth2, application commands, webhooks, stage instances, and partner SDK provisional accounts. It is the primary backbone for community automation, moderation tooling, and game integrations.

## For AI agents

Send and manage messages, channels, members, roles, and application commands across Discord servers. Useful for community moderation, gaming, and chat-automation agents.

## Scope

Does not handle real-time gateway WebSocket events, voice media transport, or video streaming - use for HTTP REST operations against guilds, channels, members, and application commands only.

## Capabilities

- Manage guilds, channels, and threads - create channels, archive threads, edit topics
- Send, edit, and delete messages, embeds, and reactions across channels via /channels/{channel.id}/messages
- Manage guild members, roles, and permissions including bans, timeouts, and role assignments
- Register and update slash commands and other application commands via /applications/{application.id}/commands
- Handle OAuth2 flows for user identity, connections, and bot installation through /oauth2/* endpoints
- Operate webhooks for one-way posting from external systems into Discord channels

## Use cases

### Community Moderation Bots

Discord bots can automate moderation across busy guilds by listening for messages, applying timeouts, removing bad actors, and logging actions. The HTTP API provides direct access to message management, member bans, role assignment, and audit log retrieval. Combined with the Gateway for real-time events, bots can react to thousands of messages per minute and keep large communities healthy without hiring round-the-clock human moderators.

Example prompt: On a flagged message in channel ID 12345, call PUT /guilds/{guild.id}/members/{user.id} to apply a 1-hour communication timeout and DELETE /channels/{channel.id}/messages/{message.id} to remove the message.

### Slash-Command Driven Game and Productivity Apps

Developers can ship slash commands that let users trigger game actions, run polls, fetch stats, or call internal APIs from within Discord. Application commands are registered via /applications/{application.id}/commands and respond through the interactions endpoint. This delivers a no-install user experience: members run commands directly inside the chat where they already collaborate.

Example prompt: Register a /stats slash command via POST /applications/{application.id}/commands, then handle the interaction by replying with the user's ranked-match win rate.

### Webhook Notifications from External Systems

Engineering teams can pipe alerts from monitoring, CI, and product systems into Discord channels using webhooks. Webhooks accept rich embeds with color-coded statuses, fields, and links, making them well suited for incident channels and release announcements. No bot user is required, and webhook URLs can be scoped per channel for clean separation.

Example prompt: POST a JSON payload with an embed describing a deployment failure to /webhooks/{webhook.id}/{webhook.token} for the #incidents channel.

### Community Analytics and Member Insights

Community managers can pull membership lists, role distributions, and channel activity via /guilds/{guild.id}/members and related endpoints to build dashboards on engagement and retention. Joined with audit log data, these analytics inform programming decisions like which channels to feature or sunset. Discord's API limits and pagination guide ETL frequency, but daily snapshots are common.

Example prompt: List guild members via /guilds/{guild.id}/members with pagination and aggregate counts by role into a daily community-health snapshot.

### AI Agent for Discord Server Management

AI agents can run as Discord-server copilots - answering questions, creating channels, registering slash commands, and posting summaries - by calling the Discord API through Jentic. Bot tokens are stored in your Jentic One instance and never reach the agent's context. Searching Jentic for 'send a Discord message' returns the right operation directly, removing the need to navigate Discord's lengthy reference docs.

Example prompt: Search Jentic for 'send a Discord message', load the schema for POST /channels/{channel.id}/messages, and execute it with content and an embed for the daily community digest.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /channels/{channel.id}/messages | Send a message to a channel |
| GET | /users/@me/guilds | List guilds the current user is a member of |
| POST | /users/@me/channels | Create a DM channel with another user |
| GET | /oauth2/userinfo | OAuth2 user info for the current token |
| GET | /gateway/bot | Get the WebSocket gateway URL and shard recommendation for bots |
| GET | /voice/regions | List available voice regions |
| GET | /oauth2/@me | Get current authorization information |

## Key resources

- **Guilds** — Create, fetch, and update servers, members, roles, bans, and audit logs
- **Channels** — Manage text, voice, stage, and forum channels and their threads
- **Messages** — Post, edit, delete messages and reactions in channels and threads
- **Application Commands** — Register and manage global and guild-scoped slash commands
- **OAuth2** — Identity, connections, bot install flow, and current application info
- **Webhooks** — Post messages from external systems into specific channels

## Why Jentic

- **Setup:** Wiring Discord by hand means carrying its bot token in the 'Bot' header, handling separate OAuth2 flows, and navigating a large REST surface across guilds and channels yourself. Through Jentic you install once, import the Discord HTTP API from the API Directory, store the bot token once, and your agent calls it.
- **Permission scoping:** Discord puts the channel id in the URL path (/channels/{channel.id}/messages), so a rule can pin your agent to one channel: it can post messages there and nothing else. You choose the operations it may call, so listing a user's guilds or opening a DM channel is not included unless you add it.
- **Credential handling:** Your Discord bot token and OAuth2 client secret are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'send a Discord message' or 'list a user's guilds', and Jentic returns the matching Discord operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Slack** — Workplace messaging and collaboration platform
- **Mattermost** — Self-hosted open-source team messaging
- **Twilio** — Multi-channel SMS, voice, and chat APIs
- **SendGrid (API Keys)** — Transactional email delivery

## FAQ

### What authentication does the Discord HTTP API use?

Discord supports two schemes: a bot token sent in the Authorization header as 'Bot <token>' for bot identities, and OAuth2 bearer tokens for user-context calls and app installation. Through Jentic, both bot tokens and OAuth client secrets are held in your Jentic One instance, and the agent receives only scoped sessions to call /channels, /guilds, and /oauth2 endpoints.

### Can I send a message to a channel with the Discord HTTP API?

Yes, POST /channels/{channel.id}/messages accepts content, embeds, components (buttons, selects), allowed_mentions, attachments, and message references for replies. The bot or webhook posting must have access to the channel and the Send Messages permission.

### What are the rate limits for the Discord HTTP API?

Discord enforces per-route, per-resource, and global bucket-based rate limits, communicated through X-RateLimit-* headers and a global cap of around 50 requests per second per bot. 429 responses include a retry_after value. Honour the headers on each request - Discord aggressively bans bots that ignore rate limit responses.

### How do I register a slash command for a Discord application through Jentic?

Search Jentic for 'register Discord slash command', load the POST /applications/{application.id}/commands operation, and execute it with the application ID and the command definition (name, description, options). For guild-scoped commands, use /applications/{application.id}/guilds/{guild.id}/commands.

### Is the Discord HTTP API free?

Yes, the Discord HTTP API is free for bots and applications, subject to Discord's Developer Terms of Service and rate limits. Some features (such as activity insights and verified bot status) require additional approval, and large bot operators must apply for verification once they reach 75 servers.

### Can I retrieve a guild's members and roles with the Discord HTTP API?

Yes, GET /guilds/{guild.id}/members lists members (with pagination via the after parameter and a limit up to 1000) and GET /guilds/{guild.id}/roles returns the role definitions. The bot must have the Server Members Intent enabled and be authorised in the guild to read full member data.

### Can I limit what my agent is allowed to do with the Discord API?

Yes. Because you run Jentic One yourself, your own rules decide which Discord operations and credentials your agent may use, and you pick the exact endpoints it can call. Since Discord puts the channel id in the URL path, such as POST /channels/{channel.id}/messages, a rule can pin the agent to a single channel so it posts there and does nothing else. Operations like listing a user's guilds via GET /users/@me/guilds or opening a DM channel via POST /users/@me/channels stay off limits unless you add them.