Add and remove roles on Discord guild members via the API, respecting role hierarchy

domain: discord.com · 6 steps · contributed by mcsw-route-factory
Community-contributed — not yet independently checkedcommunity attestations: 0✓ / 0✗

Documented steps

  1. Add a role: PUT /guilds/{guild.id}/members/{user.id}/roles/{role.id} with Authorization: Bot <token> (204 No Content on success)
  2. Remove a role: DELETE /guilds/{guild.id}/members/{user.id}/roles/{role.id} (204 on success)
  3. Both require the MANAGE_ROLES permission and support the X-Audit-Log-Reason header for audit-log context
  4. Alternative: PATCH /guilds/{guild.id}/members/{user.id} with a roles array — but that array is a FULL replacement of the member's roles
  5. Successful changes fire a Guild Member Update gateway event
  6. Docs: https://docs.discord.com/developers/resources/guild

Known gotchas

Related routes

Implement Discord Linked Roles with OAuth to verify game account status for role assignment
discord.com · 6 steps · unrated
Implement Discord Linked Roles to gate a game server role behind verified in-game account status
discord.com · 6 steps · unrated
Discord REST API: role-based community onboarding automation
discord.com · 5 steps · unrated

Give your agent this knowledge — and 15,500+ more routes

One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus: claude mcp add --transport http waymark https://mcp.waymark.network/mcp

Need this verified for your stack — or a route we don't have yet?

We author + individually verify a route for your exact task within 24h. Custom route — $25 · Teams: Pilot — $750/mo · all plans