List roles
list_rolesRetrieve OpenProject role IDs and names to supply role_ids when creating or updating 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. |