---
title: "PATCH /guilds/{guild_id}/roles/"
method: PATCH
path: "/guilds/{guild_id}/roles/"
tags: ["guilds"]
---

# PATCH /guilds/{guild_id}/roles/

`PATCH /guilds/{guild_id}/roles/`

## Path parameters

- `guild_id` string, required

## Request body

- object[]
  - `id` string, required
  - `position` integer, required

## Response `200`

- RoleResponse[]
  - `id` string, required — A Twitter-like snowflake, except the epoch is 2015-01-01T00:00:00.000Z ``` If we have a snowflake '266241948824764416' we can represent it as binary: 64 22 17 12 0 000000111011000111100001101001000101000000 00001 00000 000000000000 number of ms since Discord epoch worker pid increment ```
  - `name` string, required
  - `description` string, nullable, required
  - `color` integer, required
  - `colors` RoleColors, required
    - `primary_color` integer, required
    - `secondary_color` integer
    - `tertiary_color` integer
  - `hoist` boolean, required
  - `icon` string, nullable
  - `unicode_emoji` string, nullable
  - `position` integer, required
  - `permissions` string, required
  - `managed` boolean, required
  - `mentionable` boolean, required
  - `flags` integer
  - `tags` RoleTags
    - `bot_id` string — A Twitter-like snowflake, except the epoch is 2015-01-01T00:00:00.000Z ``` If we have a snowflake '266241948824764416' we can represent it as binary: 64 22 17 12 0 000000111011000111100001101001000101000000 00001 00000 000000000000 number of ms since Discord epoch worker pid increment ```
    - `integration_id` string — A Twitter-like snowflake, except the epoch is 2015-01-01T00:00:00.000Z ``` If we have a snowflake '266241948824764416' we can represent it as binary: 64 22 17 12 0 000000111011000111100001101001000101000000 00001 00000 000000000000 number of ms since Discord epoch worker pid increment ```
    - `subscription_listing_id` string — A Twitter-like snowflake, except the epoch is 2015-01-01T00:00:00.000Z ``` If we have a snowflake '266241948824764416' we can represent it as binary: 64 22 17 12 0 000000111011000111100001101001000101000000 00001 00000 000000000000 number of ms since Discord epoch worker pid increment ```
    - `premium_subscriber` boolean, nullable
    - `available_for_purchase` boolean, nullable
    - `guild_connections` boolean, nullable

## Other responses

- `400`
- `403`

## Changes

- **2026-06-13** `15d60f485759` — 6 breaking, 4 info
  - the response property `items/icon` became nullable for the status `200`
  - the response property `items/tags/premium_subscriber` became nullable for the status `200`
  - the response property `items/unicode_emoji` became nullable for the status `200`
  - the response property `items/flags` became optional for the status `200`
  - …6 more
- **2026-04-28** `d209eb052880` — 1 info
  - endpoint added
- **2026-04-19** `1cde78e24558` — 1 breaking
  - api path removed without deprecation
- **2026-03-16** `0fa8e94de7e7` — 1 breaking
  - removed the required property `items/__@annotationsKey@12300` from the response with the `200` status
- **2026-03-14** `f3ce58d12e93` — 1 breaking, 1 info
  - removed the required property `items/__@annotationsKey@12306` from the response with the `200` status
  - added the required property `items/__@annotationsKey@12300` to the response with the `200` status
  - …this revision’s changelog is incomplete

[Full history](https://skmtc.dev/spacebarchat/apis/spacebar-server/changes/guilds/:guild_id/roles/patch.md)

---

[API](https://skmtc.dev/spacebarchat/apis/spacebar-server.md) · [All operations](https://skmtc.dev/spacebarchat/apis/spacebar-server/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/spacebarchat/spacebar-server/revisions/a15db2c050e7/schema)