---
title: "Update role"
method: PATCH
path: "/role/{id}"
tags: ["Roles"]
---

# Update role

`PATCH /role/{id}`

## Request

- Base URL: `https://api.elaichi.ai`
- URL: `https://api.elaichi.ai/role/{id}`
- Auth: HTTP bearer

Updates a custom role. **`permissions` is REPLACED wholesale, not merged** — the array you send becomes the role's entire permission set, so anything omitted is revoked from every member holding the role. Read the role first and send the full intended list. Omitting `permissions` entirely leaves it untouched. Edits apply immediately: effective permissions are recomputed on every request. Requires `role:manage`, the `custom_roles` feature, and that you hold every permission you are granting.

## Path parameters

- `id` string, required

## Headers

- `X-Organization-Id` string

## Request body

- object
  - `name` string
  - `description` string, nullable
  - `permissions` string[]: Replaces the role's permission set entirely.

## Response `200`

OK

- Role
  - `id` string: Role id (`role_…`).
  - `name` string
  - `description` string, nullable
  - `is_system` boolean: Predefined roles ship with every organization and cannot be edited away.
  - `seat_class` 'billable' | 'free_admin': Whether members holding only this role count toward billable seats.
  - `permissions` string[]: Every permission the role holds, including any `GET /permission` does not list for this organization (for example the Apps permissions while Apps are unavailable). `PATCH /role/{id}` replaces this list wholesale, so send back the entries you did not mean to remove.
  - `permission_count` integer: How many of `permissions` `GET /permission` lists for this organization: the number to show beside the role. Can be lower than `permissions.length`.
  - `member_count` integer: How many members hold this role right now. `GET /member?role_id={id}` lists them; while it is above zero, `DELETE /role/{id}` needs `reassign_to` (or, on `POST /role/{id}/delete`, `reassign_to` and/or a `reassignments` entry for every holder).
  - `pending_invite_count` integer: Pending invites issued for this role. Present only on roles you can manage. While above zero, `DELETE /role/{id}` and `POST /role/{id}/delete` need `reassign_to`, which re-points them.
  - `group_mapping_count` integer: SCIM group mappings that assign this role. Present only on roles you can manage. While above zero, `DELETE /role/{id}` is refused (`409 role_mapped`) until the mappings change.
  - `can_reassign_holders` boolean: Whether you may move this role's holders and pending invites to another role (`DELETE /role/{id}?reassign_to=` or `POST /role/{id}/delete`): you hold `member:manage` and do not hold this role yourself.
  - `created_at` string, date-time
  - `updated_at` string, date-time

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `429`: Rate limited

---

[API](https://skmtc.dev/elaichi/apis/elaichi-api.md) · [All operations](https://skmtc.dev/elaichi/apis/elaichi-api/llms.txt) · [OpenAPI document](https://skmtc.dev/elaichi/apis/elaichi-api/revisions/b22cfb7b6d15?raw)