Revoke a role

POST /v1/roles/revoke · requires roles:manage

Body parameters

Behaves exactly like Grant a role in reverse, with the same permission requirements, the same errors and the same 403 when the bot's role is lower than the target role. A member who does not have the role is not an error.

The same roles are rejected as on Grant a role, so a key cannot revoke a moderator, administrator or bot master role from anyone either: see Roles a key can change. The change shows in your server's audit log in Discord with the reason API key: followed by the name of the key.

Returns

Example

curl -X POST https://ceejay.communitystudios.xyz/api/v1/roles/revoke \
  -H "Authorization: Bearer $CEEJAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "discordId": "409876543210987654",
    "roleId": "982371004827100394"
  }'

The TypeScript example uses ceejay.roles.revoke from the TypeScript SDK. It returns the data of the response below.

{
  "success": true,
  "data": {
    "discordId": "409876543210987654",
    "roleId": "982371004827100394",
    "action": "revoked",
    "duplicate": false
  }
}

Retrying safely

Send an idempotencyKey with every call you might need to retry, such as after a timeout. It is a string of 1 to 128 characters that you choose, sent in the JSON body: an Idempotency-Key header is not read.

• Retrying with the same key returns the original response. When the same request is sent again with its key, CEEJAY returns the original response, with duplicate: true and the header Idempotent-Replayed: true.
• Each key is tied to one request payload. The same request means the same member and role. Two requests for one event need two keys, for example match-9:coins and match-9:xp. A key that was used for a different request, here or on any other request of the API, returns 409 with the code idempotency_key_reused, and nothing is changed.
• A rejected request does not use up the key. A call that was rejected can be retried with the same key once the cause is fixed.
• A key belongs to the API key that sent it. Another API key of your community can send the same text, and it is a different key.
• Keys are retained for 30 days. Use a value you can regenerate after a crash, such as an order ID or a match ID.
• On an instance that does not support idempotency keys yet, a call that sends one returns 503 with the code idempotency_unavailable, and nothing is changed. Community details reports whether keys are supported, under features.retryKeys. idempotency_key is not accepted on this endpoint; use idempotencyKey.
• Without a key, a retried call is a new call.

Revoking a role is idempotent, so when a first request was started more than a minute ago and never finished, a retry with the same key makes the change again and returns normally. The request is also safe to repeat without a key.

Errors

Discord's own rate limit returns 429 with the code discord_rate_limited. That response does not mean your key's own limit is used up: X-RateLimit-Remaining still shows what the key has left.

Every error body also includes requestId, and a 400 with the code bad_request identifies the invalid field in field. Match on code; message text can change.

The errors every request shares (401, 403, 405, 429, 500) are on the Errors page.