---
title: "Get Role"
api: "GET /v1/api/roles-and-permissions/roles/{roleId}"
description: "Retrieve a specific role by its ID."
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:view` 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. An ID that matches no role in the workspace returns `404`.
</ParamField>

## Response Fields

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

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

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

<ResponseField name="permissions" type="object">
Permissions grouped by category. Each key is a category and its value is the list of permission keys.
</ResponseField>

<ResponseField name="isSystem" type="boolean">
`true` for the built-in roles (`owner`, `admin`, `editor`, `viewer`).
</ResponseField>

<ResponseField name="workspaceId" type="string">
Workspace the role belongs to. Absent on system roles.
</ResponseField>

<ResponseField name="createdAt" type="string">
Timestamp when the role was created.
</ResponseField>

<ResponseField name="updatedAt" type="string">
Timestamp when the role was last updated.
</ResponseField>

<Note>
  This endpoint doesn't return the role's users. Use [List Roles](https://trillet-ai.jamdesk.app/v1/api-reference/endpoints/roles/list), which includes `userIds` for each role.
</Note>

<ResponseExample>
```json
{
  "_id": "a4a4a4a4a4a4a4a4a4a4a4a4",
  "workspaceId": "a1a1a1a1a1a1a1a1a1a1a1a1",
  "name": "Agent Manager",
  "description": "Can manage agents and view call history",
  "permissions": {
    "agent": ["agent:view", "agent:create", "agent:edit"],
    "call_history": ["call_history:view"]
  },
  "isSystem": false,
  "createdAt": "2024-06-01T09:00:00.000Z",
  "updatedAt": "2024-06-01T09:00:00.000Z",
  "__v": 0
}
```

```json 404
{
  "error": "Role not found"
}
```
</ResponseExample>


---

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