List roles

GET /v1/roles · requires roles:manage

Use it to find the roleId that Grant a role and Revoke a role need, and to see beforehand which roles those two requests reject. It takes no parameters.

Returns

data is a list of roles, highest first, without @everyone. The whole list is returned in one response, so page.nextCursor is always null and page.limit is the number of roles.

Prop

Type

Example

Request

curl "https://ceejay.communitystudios.xyz/api/v1/roles" \
  -H "Authorization: Bearer $CEEJAY_API_KEY"

The TypeScript example uses ceejay.roles.list from the TypeScript SDK. It returns the full response below, with the list in data.

200 OK

{
  "success": true,
  "data": [
    {
      "roleId": "982371004827100301",
      "name": "Moderator",
      "color": 15158332,
      "position": 12,
      "managed": false,
      "grantable": false,
      "notGrantableReason": "can_moderate"
    },
    {
      "roleId": "982371004827100394",
      "name": "Tournament winner",
      "color": 15844367,
      "position": 5,
      "managed": false,
      "grantable": true,
      "notGrantableReason": null
    },
    {
      "roleId": "982371004827100377",
      "name": "Server Booster",
      "color": 16023551,
      "position": 4,
      "managed": true,
      "grantable": false,
      "notGrantableReason": "managed"
    }
  ],
  "page": {
    "nextCursor": null,
    "limit": 3
  }
}

Which roles a key may change

grantable is decided by the same checks the two role requests make: see Roles a key can change.

`notGrantableReason`	The role
`null`	Can be granted and revoked through the API
`managed`	Is managed by Discord or by another app, such as a bot's own role or the server booster role
`can_moderate`	Can moderate or manage the server
`can_mention_everyone`	Can mention `@everyone`, `@here` and all roles, in a server whose `@everyone` role cannot. Where `@everyone` can, the role adds nothing and is not excluded for this reason
`dashboard_access`	Is one of your community's bot master roles, which give access to the CEEJAY dashboard
`above_bot`	Is at or above the CEEJAY bot's highest role in the role hierarchy, so Discord would reject the change. Move the CEEJAY role higher in Server Settings → Roles

above_bot is reported when CEEJAY could read the bot's own highest role. When it could not, the reason is never reported, and Discord may still reject such a role with 403. A role that has moderation permissions only through channel permission overwrites cannot be seen from the role list.

CEEJAY reads the list from Discord and caches it for up to a minute. A role is never reported as grantable when your community's bot master roles could not be read: the call then returns 503.

The list never returns a role's permissions, which members have it, or the tags of a managed role.

Errors

Status	`code`	`error`	When
`429`	`discord_rate_limited`	`Discord API rate limited, try again later`	Discord is rate limiting the bot. `retryAfter` and the `Retry-After` header contain the wait Discord requested, in whole seconds, if it gave one. Do not retry in a tight loop
`500`	`discord_not_configured`	`This instance cannot reach Discord yet`	This instance has no connection to Discord yet
`503`	`roles_unavailable`	`Could not read this server's roles from Discord`	The server's roles could not be read from Discord, so nothing is listed. Retry with a pause between attempts
`503`	`dashboard_roles_unavailable`	`Could not read which roles give access to the CEEJAY dashboard, so no role is listed`	CEEJAY could not read which roles are your community's bot master roles, so nothing is listed. Retry with a pause between attempts

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.

Returns

Example

Which roles a key may change

Errors

On this page