List Roles

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

GET /api/v1/roles

cURL

curl "https://api.wordsmith.ai/api/v1/roles" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here"

Response

{
  "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
}

Preview. This endpoint is available to organisations in the Wordsmith MCP pilot. Other organisations receive 403 mcp_not_enabled. See the preview overview.

Lists the roles in your organisation. Use it to resolve the custom_role_ids on a member, or to find a role to pass to Update Member or 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. Predefined roles come first, in the order viewer, full_user, admin, then custom roles by name.

cURL

curl "https://api.wordsmith.ai/api/v1/roles" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here"

Response

{
  "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.