post
/guilds/{guild_id}/rolesCreate guild role
Create guild role. Requires manage_roles permission. Creates a new role with specified name, permissions, and color.
create_guild_role
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| guild_id* | path | SnowflakeType | The ID of the guild |
Request body
application/json
json
{
"type": "object",
"properties": {
"name": {
"description": "The name of the role (1-100 characters)",
"type": "string"
},
"color": {
"default": 0,
"description": "The color of the role as an integer (default: 0)",
"$ref": "#/components/schemas/ColorType"
},
"permissions": {
"description": "The permissions bitfield for the role",
"$ref": "#/components/schemas/UnsignedInt64Type"
}
},
"required": [
"name"
]
}Responses
200
Success
json
{
"type": "object",
"properties": {
"id": {
"description": "The unique identifier for this role",
"$ref": "#/components/schemas/SnowflakeStringType"
},
"name": {
"type": "string",
"description": "The name of the role"
},
"color": {
"description": "The colour of the role as an integer",
"$ref": "#/components/schemas/Int32Type"
},
"position": {
"description": "The position of the role in the role hierarchy",
"$ref": "#/components/schemas/Int32Type"
},
"hoist_position": {
"description": "The position of the role in the hoisted member list",
"anyOf": [
{
"$ref": "#/components/schemas/Int32Type"
},
{
"type": "null"
}
]
},
"permissions": {
"description": "The permissions bitfield for the role",
"$ref": "#/components/schemas/Permissions"
},
"hoist": {
"type": "boolean",
"description": "Whether this role is displayed separately in the member list"
},
"mentionable": {
"type": "boolean",
"description": "Whether this role can be mentioned by anyone"
},
"unicode_emoji": {
"description": "The unicode emoji for this role",
"type": [
"string",
"null"
]
}
},
"required": [
"id",
"name",
"color",
"position",
"permissions",
"hoist",
"mentionable"
],
"additionalProperties": false
}400
Bad Request - The request was malformed or contained invalid data
json
{
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Machine-readable error code"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"errors": {
"description": "Field-specific validation errors",
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "Field path that failed validation"
},
"code": {
"description": "Machine-readable validation error code",
"type": "string"
},
"message": {
"type": "string",
"description": "Human-readable validation error message"
}
},
"required": [
"path",
"message"
],
"additionalProperties": false
}
}
},
"required": [
"code",
"message"
],
"additionalProperties": {}
}401
Unauthorized - Authentication is required or the token is invalid
json
{
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Machine-readable error code"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"errors": {
"description": "Field-specific validation errors",
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "Field path that failed validation"
},
"code": {
"description": "Machine-readable validation error code",
"type": "string"
},
"message": {
"type": "string",
"description": "Human-readable validation error message"
}
},
"required": [
"path",
"message"
],
"additionalProperties": false
}
}
},
"required": [
"code",
"message"
],
"additionalProperties": {}
}403
Forbidden - You do not have permission to perform this action
json
{
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Machine-readable error code"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"errors": {
"description": "Field-specific validation errors",
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "Field path that failed validation"
},
"code": {
"description": "Machine-readable validation error code",
"type": "string"
},
"message": {
"type": "string",
"description": "Human-readable validation error message"
}
},
"required": [
"path",
"message"
],
"additionalProperties": false
}
}
},
"required": [
"code",
"message"
],
"additionalProperties": {}
}429
Too Many Requests - You are being rate limited
json
{
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Machine-readable error code"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"errors": {
"description": "Field-specific validation errors",
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "Field path that failed validation"
},
"code": {
"description": "Machine-readable validation error code",
"type": "string"
},
"message": {
"type": "string",
"description": "Human-readable validation error message"
}
},
"required": [
"path",
"message"
],
"additionalProperties": false
}
},
"retry_after": {
"type": "number",
"description": "Seconds to wait before retrying"
},
"global": {
"type": "boolean",
"description": "Whether this is a global rate limit"
}
},
"required": [
"code",
"message"
],
"additionalProperties": {}
}500
Internal Server Error - An unexpected error occurred
json
{
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Machine-readable error code"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"errors": {
"description": "Field-specific validation errors",
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "Field path that failed validation"
},
"code": {
"description": "Machine-readable validation error code",
"type": "string"
},
"message": {
"type": "string",
"description": "Human-readable validation error message"
}
},
"required": [
"path",
"message"
],
"additionalProperties": false
}
}
},
"required": [
"code",
"message"
],
"additionalProperties": {}
}