List notifications
list_notificationsFetch your OpenProject inbox notifications about mentions, assignments, and watched items, with filters for project, reason, and read/unread state.
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. |