roles_create
roles_create
Section titled “roles_create”Category: roles
Create a new role in a guild.
When to use
Section titled “When to use”- Programmatic role provisioning (e.g. tier-based roles, integration roles).
permissions is a base-10 STRING (Discord permission integer; bitfields exceed JS number safety).
When NOT to use
Section titled “When NOT to use”| Field | Type | Required | Description |
|---|---|---|---|
guild_id | string | yes | Target guild |
name | string | no | Role name (default “new role”) |
permissions | string | no | Permission bitfield as base-10 string |
color | integer | no | RGB color integer |
hoist | boolean | no | Display members with this role separately in the sidebar |
icon | unknown | no | Role icon (data URI; requires guild boost level) |
unicode_emoji | unknown | no | Role unicode emoji (requires ROLE_ICONS feature) |
mentionable | boolean | no | Whether @-mentioning the role notifies members |
audit_reason | string | no | Reason recorded in audit log (X-Audit-Log-Reason header) |
Returns
Section titled “Returns”\{id, name, color, position, permissions, mentionable, hoist\}.
Output schema
Section titled “Output schema”| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | Discord role ID |
name | string | yes | |
color | integer | yes | |
position | integer | yes | |
permissions | string | yes | |
mentionable | boolean | yes | |
hoist | boolean | yes |
Annotations
Section titled “Annotations”| Property | Value |
|---|---|
| Read-only | no |
| Destructive | no |
| Idempotent | no |
| Open-world | yes |
| Confirmation required | no |