---
title: "List Roles"
api: "GET /v1/api/roles-and-permissions/roles"
description: "Retrieve all roles defined in your workspace."
---

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

## Response Fields

<ResponseField name="roles" type="array">
Array of role objects.

<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="array">
Array of permission objects.
</ResponseField>

<ResponseField name="userIds" type="array">
Array of user IDs assigned to this role.
</ResponseField>

</ResponseField>

<ResponseExample>
```json
[
  {
    "_id": "665a1b2c3d4e5f6a7b8c9d0e",
    "name": "Admin",
    "description": "Full access to all workspace features",
    "permissions": [
      { "key": "agent_view", "category": "agents" },
      { "key": "agent_create", "category": "agents" }
    ],
    "userIds": ["user_001", "user_002"]
  },
  {
    "_id": "665a1b2c3d4e5f6a7b8c9d0f",
    "name": "Viewer",
    "description": "Read-only access",
    "permissions": [
      { "key": "agent_view", "category": "agents" },
      { "key": "call_history_view", "category": "calls" }
    ],
    "userIds": ["user_003"]
  }
]
```
</ResponseExample>