roles_list

Fetch all roles with their colors, permissions, and positions. Clients use it to style usernames, render role badges, and build role settings screens.

Request

{
  "cmd": "roles_list"
}

No fields besides cmd.

Response

{
  "cmd": "roles_list",
  "val": {
    "owner": {
      "id": "3f0c9a52-7d0e-4c8e-9a51-0b6f1f7f2d11",
      "name": "owner",
      "description": "Server owner with ultimate permissions.",
      "color": "#9400D3",
      "gradient": null,
      "hoisted": true,
      "permissions": ["owner", "administrator"],
      "self_assignable": false,
      "category": null,
      "position": 0
    },
    "photography": {
      "id": "b7e2d6a1-54c3-4f7a-8e0d-2c9f61a3e4b8",
      "name": "photography",
      "description": "Share your shots",
      "color": "#a78bfa",
      "icon": "https://example.com/roles/camera.png",
      "gradient": [],
      "hoisted": false,
      "permissions": [],
      "self_assignable": true,
      "category": "Hobbies",
      "price": 0,
      "position": 4
    }
  }
}

val maps each role name to a role object. Each object repeats its key in name.

Object key order is not role order. Sort by position to display roles. A lower position is a higher rank.
Not every role has every field. The built-in roles, and roles from older servers, may lack icon or price, and may have null for gradient or category. Treat a missing field as empty.

Permissions

Any member can call it.

Errors

This command has no command-specific errors.

See also