---
title: "Update Role"
api: "PUT /v1/api/roles-and-permissions/roles/{roleId}"
description: "Update an existing role's name, description, permissions, or assigned users."
lastUpdated: "2026-11-04"
---

> **For AI agents:** the complete documentation index is at [llms.txt](https://trillet-ai.jamdesk.app/llms.txt). Append `.md` to any page URL for its markdown version.

Requires the `role:edit` permission in the workspace.

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Path Parameters

<ParamField path="roleId" type="string" required>
The unique identifier of the role to update.
</ParamField>

## Request Body

<ParamField body="name" type="string">
Updated name for the role.
</ParamField>

<ParamField body="description" type="string">
Updated description for the role. Must not be empty.
</ParamField>

<ParamField body="permissions" type="array of strings">
The complete new set of permission keys, in `category:action` form (e.g., `"agent:view"`). This replaces the role's permissions; it is not merged with them. At least one key is required when the field is sent. Use [List Permissions](https://trillet-ai.jamdesk.app/v1/api-reference/endpoints/roles/list-permissions) for the available keys.
</ParamField>

<ParamField body="userIds" type="array of strings" required>
User IDs to assign this role to, in addition to the users who already hold it. Send `[]` to assign no one new.
</ParamField>

<Note>
  For the built-in system roles (`owner`, `admin`, `editor`, `viewer`), only `userIds` is applied. The name, description and permissions of a system role can't be changed.
</Note>

## Response

<ResponseField name="_id" type="string">
Unique identifier for the role.
</ResponseField>

<ResponseField name="name" type="string">
Updated name of the role.
</ResponseField>

<ResponseField name="description" type="string">
Updated description of the role.
</ResponseField>

<ResponseField name="permissions" type="object">
Permissions grouped by category, as in [Create Role](https://trillet-ai.jamdesk.app/v1/api-reference/endpoints/roles/create).
</ResponseField>

<RequestExample>
```json
{
  "name": "Senior Manager",
  "description": "Manages agents and reviews call history",
  "permissions": [
    "agent:view",
    "agent:create",
    "agent:edit",
    "agent:delete",
    "call_history:view"
  ],
  "userIds": []
}
```
</RequestExample>

<ResponseExample>
```json
{
  "_id": "a4a4a4a4a4a4a4a4a4a4a4a4",
  "workspaceId": "a1a1a1a1a1a1a1a1a1a1a1a1",
  "name": "Senior Manager",
  "description": "Manages agents and reviews call history",
  "permissions": {
    "agent": ["agent:view", "agent:create", "agent:edit", "agent:delete"],
    "call_history": ["call_history:view"]
  },
  "isSystem": false,
  "createdAt": "2024-06-01T09:00:00.000Z",
  "updatedAt": "2024-06-02T10:30:00.000Z",
  "__v": 0
}
```
</ResponseExample>


---

📦 **OpenAPI specs:** Every OpenAPI specification referenced by this documentation is available as a single download — https://trillet-ai.jamdesk.app/api-specs.zip
