role_reorder

Set the rank order of roles. Rank decides which roles a member can manage: only roles below their highest role. Clients also sort roles by position for display.

Request

{
  "cmd": "role_reorder",
  "roles": ["owner", "admin", "moderator", "photography", "user"]
}

Field	Type	Required	Description
`roles`	string[]	Yes	Role names or IDs, highest rank first. At least one entry. Every entry must be an existing role.

The server sets each listed role’s position from its place in the list, so the first role gets the lowest position, which is the highest rank. Send the full list: roles you leave out keep their old position, which can then clash with a listed role.

Response

{
  "cmd": "role_reorder",
  "val": true,
  "roles": ["owner", "admin", "moderator", "photography", "user"]
}

roles echoes your list as sent. Every other authenticated connection receives the same frame. Fetch roles_list to read the new position values. The change is recorded in the audit log.

Permissions

Requires manage_roles. It is blocked while you are timed out.

The role hierarchy isn’t checked here. Anyone with manage_roles can move any role, including owner and roles above their own.

Errors

`val`	When
`Failed to reorder roles. Ensure all roles in the list exist.`	An entry doesn’t match any role, or the server could not save the change.
Validation message	`roles` is missing, empty, or contains a non-string.

See also