---
title: "List Roles"
api: "GET /v1/api/roles-and-permissions/roles"
description: "Retrieve all roles available in your workspace, including the built-in system roles."
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.

The response is a bare array. It contains the workspace's custom roles plus the four built-in system roles, `owner`, `admin`, `editor` and `viewer` (lowercase, `isSystem: true`). System roles have no `workspaceId`.

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</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 (e.g., `"agent": ["agent:view", "agent:edit"]`).
</ResponseField>

<ResponseField name="isSystem" type="boolean">
`true` for the built-in roles, which can't be edited or deleted.
</ResponseField>

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

<ResponseField name="userIds" type="array of strings">
IDs of the users in this workspace who hold the role.
</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>

<ResponseExample>
```json
[
  {
    "_id": "c8c8c8c8c8c8c8c8c8c8c8c8",
    "name": "editor",
    "description": "Can edit content and users but not billing or subscriptions.",
    "permissions": {
      "agent": ["agent:create", "agent:view", "agent:edit", "agent:delete"],
      "call_history": ["call_history:view"]
    },
    "isSystem": true,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z",
    "__v": 0,
    "userIds": []
  },
  {
    "_id": "a4a4a4a4a4a4a4a4a4a4a4a4",
    "workspaceId": "a1a1a1a1a1a1a1a1a1a1a1a1",
    "name": "Manager",
    "description": "Full access to agents and 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,
    "userIds": ["a8a8a8a8a8a8a8a8a8a8a8a8"]
  }
]
```
</ResponseExample>


---

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