List notifications
list_notificationsRetrieve your OpenProject inbox to see what needs attention, including mentions, assignments, and changes to watched items. Filter by project, reason, or unread status and paginate results.
Instructions
Read the authenticated user's OpenProject inbox.
Use this to answer "what needs my attention?", "was I mentioned anywhere?" or "what changed on the things I watch?" — it is the only tool that sees notifications, and it always reports the inbox of the token owner, never another user's.
Returns the standard list envelope: items of {id, reason, read, created_at, actor, project, resource} plus pagination with
total/page/page_size/has_more. resource is the thing
the notification is about — {id, type, title}, usually
type='WorkPackage', so resource.id feeds straight into
get_work_package or list_work_package_comments.
Pitfalls. Several changes to the same work package are aggregated into
one notification, so the count is not a count of events. Reading a
notification here does not mark it read — that is
mark_notifications. unread_only=false can return a very long
history; keep a page size that fits your reply. A notification whose
project the token owner has lost access to disappears from the inbox
entirely.
Cross-references: mark specific rows read with mark_notifications;
clear the whole (optionally filtered) inbox with
mark_all_notifications_read; open the underlying ticket with
get_work_package(resource.id) and its discussion with
list_work_package_comments(resource.id).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-based page number. | |
| reason | No | Restrict to one trigger: mentioned, assigned, responsible, watched, subscribed, commented, created, processed, prioritized, scheduled, shared, reminder, dateAlert. 'mentioned' is what answers "who needs me?". dateAlert filtering is an OpenProject Enterprise feature and is rejected with an explanatory hint on Community instances. | |
| page_size | No | Notifications per page (max 100); the instance may clamp it lower and the returned pagination reports what actually came back. | |
| project_id | No | Numeric project id or identifier to scope the inbox to one project. Ids come from list_projects. | |
| unread_only | No | true (default) returns only notifications still unread in the in-app inbox; false returns read and unread together. There is no 'read only' mode — filter the rows on read=false/true yourself if you need one. |
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. |