List roles
list_rolesRetrieve all roles defined in the OpenProject instance, each with its unique ID and name. Use the returned IDs to assign roles when creating or updating project memberships.
Instructions
List the roles this instance defines, with their ids.
This is the id-producing tool for create_membership.role_ids and
update_membership.role_ids — role names are never accepted there.
Roles are instance-wide definitions ('Member', 'Reader', 'Project
admin'); a membership binds one principal to one project with a set of
them.
Returns the standard list envelope with has_more: false: the role list
is small and fetched in full. Each item is {id, name}, plus
permissions when include_permissions=true.
Pitfalls. Role names are configurable per instance, so do not assume
'Member' exists — read the list. Some roles are not assignable to a
project membership (global and work-package roles live in the same
collection); the membership form rejects those with the assignable set
listed. Not every OpenProject version exposes permission arrays on this
endpoint: when include_permissions=true returns none, notes says so
rather than pretending the roles grant nothing.
Cross-references: create_membership / update_membership consume these
ids; list_memberships shows which roles are in use; list_permissions
answers what the current user may do, which is the more useful question
when a call just failed with 403.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| include_permissions | No | Add each role's full permission identifier array. Off by default because those arrays are long — a dozen roles can run to thousands of tokens. Turn it on only when the question is genuinely 'what does this role allow'. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sums | No | Present only when show_sums was requested. | |
| items | No | The page of results. | |
| notes | No | Degradation markers: capped aggregations, unavailable modules, … | |
| groups | No | Present only when group_by was requested. | |
| pagination | Yes | Total/page/page_size/has_more. |