> ## Documentation Index
> Fetch the complete documentation index at: https://wordsmithai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# List Roles

> List the built-in and custom roles you can assign to members.

> [!NOTE]
>
> **Preview.** This endpoint is available to organisations in the Wordsmith MCP pilot. Other organisations receive `403 mcp_not_enabled`. See the [preview overview](/preview).

Lists the [roles](/proposed/objects#organisation) in your organisation. Use it to resolve the `custom_role_ids` on a [member](/api-reference/organisation/get-member), or to find a role to pass to [Update Member](/api-reference/organisation/update-member) or [Create Invite](/api-reference/organisation/create-invite).

There are two kinds:

* **Predefined roles** have `type: "predefined"` and the fixed ids `viewer`, `full_user` and `admin`. Every organisation has them. An admin can turn one off, which sets `active` to `false`.
* **Custom roles** have `type: "custom"` and a UUID id. Your admins build them from permission groups in Settings. They appear only on plans that include custom roles.

A role with `active: false` cannot be assigned. `member_count` counts the members who hold the role, suspended members included. Predefined roles have no `description`.

Creating and editing custom roles is not part of this proposal. Do that in Settings.

## Authentication

Requires an API key, or an OAuth token with `directory:read`. The caller must also be able to assign or manage roles: an organisation admin, or a role with either permission.

## Query parameters

**type** `enum`

Return only `predefined` or only `custom` roles.

**cursor** `string`

The `cursor` from the previous page.

**limit** `integer` (default: 50)

Roles per page, up to 200.

## Response

Returns `200` with a page of [roles](/proposed/objects#organisation). Predefined roles come first, in the order `viewer`, `full_user`, `admin`, then custom roles by name.

```bash cURL theme={null}
curl "https://api.wordsmith.ai/api/v1/roles" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here"
```

```json Response theme={null}
{
  "items": [
    {
      "id": "viewer",
      "name": "Viewer",
      "type": "predefined",
      "description": null,
      "active": true,
      "member_count": 4
    },
    {
      "id": "full_user",
      "name": "Full user",
      "type": "predefined",
      "description": null,
      "active": true,
      "member_count": 37
    },
    {
      "id": "admin",
      "name": "Admin",
      "type": "predefined",
      "description": null,
      "active": true,
      "member_count": 3
    },
    {
      "id": "72f02d30-2d67-40b0-b5cb-859dbb45d485",
      "name": "Contracts manager",
      "type": "custom",
      "description": "Manages the contract repository and company reports.",
      "active": true,
      "member_count": 6
    }
  ],
  "cursor": null
}
```

## Errors

| Status | `error_code` | When |
| - | - | - |
| 400 | `bad_request` | `type` is not `predefined` or `custom`, `limit` is outside 1 to 200, or `cursor` is not valid. |
| 403 | `insufficient_scope` | The OAuth token does not hold `directory:read`. |
| 403 | `forbidden` | The caller can neither assign roles nor manage them. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.