Notifications
Read, mark, delete, and configure the notifications of the person who owns the credential, in one workspace.
These endpoints act as the key owner, in the workspace the credential is bound to. A personal API token selects the workspace with the X-Project-Feed-Workspace header. Notifications from every workspace are on the Identity API.
Session tokens can read and change your preferences for the workspace in X-Project-Feed-Workspace, including as a viewer, because they are your own settings.
Endpoints
- Scope
- notifications:read
Query parameters
unreadstringSet to "true" to filter to unread notifications only
sincestringOnly notifications created at or after this time, so the last createdAt you saw comes back and a notification created in the same millisecond is not missed. Skip ids you already have. Epoch milliseconds, or an ISO 8601 time with a timezone. Other values return 400. An aggregated notification counts again when it gains new activity.
typestringOnly these notification types, as a comma-separated list of at most 16
projectIdstringOnly notifications about this project, by ID or slug
limitnumberNumber of notifications (max 100, default 50)
offsetnumberPagination offset (max 10000, default 0)
cursorstringContinue from nextCursor, even if the previous page was empty. Omit it or pass start for the first page. Keep paging while hasMore is true.
Request
curl --request GET \
--url 'https://projectfeed.app/api/v1/notifications' \
--header 'Authorization: Bearer pf_YOUR_API_KEY'Response
{
"notifications": [
{
"id": "ntf_abc123",
"type": "comment",
"title": "New comment",
"body": "Jane commented on your post",
"read": false,
"resourceType": "post",
"resourceId": "pst_abc123",
"createdAt": 1706795400000,
"actor": {
"id": "usr_def456",
"name": "Jane Smith",
"image": "/api/media/avatars/jane.jpg"
}
}
],
"pageCount": 1,
"hasMore": true,
"truncated": false,
"nextCursor": "opaque-continuation"
}- Scope
- notifications:read
Request
curl --request GET \
--url 'https://projectfeed.app/api/v1/notifications/unread-count' \
--header 'Authorization: Bearer pf_YOUR_API_KEY'Response
{ "count": 12 }- Scope
- notifications:read
Request
curl --request GET \
--url 'https://projectfeed.app/api/v1/notifications/summary' \
--header 'Authorization: Bearer pf_YOUR_API_KEY'Response
{
"byType": { "comment": 4, "mention": 1, "task_assigned": 2 },
"total": 7,
"capped": false
}- Scope
- notifications:read
Query parameters
limitnumberNumber of projects, 1 to 100 (default 50)
cursorstringnextCursor from the previous response
Request
curl --request GET \
--url 'https://projectfeed.app/api/v1/notifications/projects' \
--header 'Authorization: Bearer pf_YOUR_API_KEY'Response
{
"projects": [
{
"projectId": "prj_abc123",
"projectName": "Product Launch",
"projectSlug": "product-launch",
"level": "watching"
}
],
"hasMore": false,
"nextCursor": null
}- Scope
- notifications:write
Request
curl --request POST \
--url 'https://projectfeed.app/api/v1/notifications/read-all' \
--header 'Authorization: Bearer pf_YOUR_API_KEY'Response
{ "success": true, "count": 12 }- Scope
- notifications:write
Path parameters
idstringrequiredNotification ID (URL path)
Body parameters
readbooleanrequiredMark as read (true) or unread (false)
Request
curl --request PATCH \
--url 'https://projectfeed.app/api/v1/notifications/ntf_abc123' \
--header 'Authorization: Bearer pf_YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"read": true
}'Response
{ "success": true }- Scope
- notifications:write
Path parameters
idstringrequiredNotification ID (URL path)
Request
curl --request DELETE \
--url 'https://projectfeed.app/api/v1/notifications/ntf_abc123' \
--header 'Authorization: Bearer pf_YOUR_API_KEY'Response
{ "success": true }- Scope
- notifications:write
Body parameters
notificationIdsstring[]Notification IDs, 1 to 100. Send notificationIds or postId, not both.
postIdstringPost ID, number, or identifier. Marks the unread notifications about that post. continuing is true when a large set is still being marked in the background.
Request
curl --request POST \
--url 'https://projectfeed.app/api/v1/notifications/read' \
--header 'Authorization: Bearer pf_YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"notificationIds": [
"notificationIds_abc123"
]
}'Response
{ "success": true, "count": 2 }- Scope
- notifications:write
Request
curl --request POST \
--url 'https://projectfeed.app/api/v1/notifications/delete-read' \
--header 'Authorization: Bearer pf_YOUR_API_KEY'Response
{ "success": true, "count": 12 }- Scope
- notifications:write
Body parameters
olderThanDaysnumberrequiredAge in whole days, at least 1
Request
curl --request POST \
--url 'https://projectfeed.app/api/v1/notifications/delete-old' \
--header 'Authorization: Bearer pf_YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"olderThanDays": 1
}'Response
{ "success": true, "count": 40 }- Scope
- notifications:write
Path parameters
projectIdstringrequiredProject ID (URL path)
Body parameters
levelstringrequireddefault, watching, or muted
Request
curl --request PUT \
--url 'https://projectfeed.app/api/v1/notifications/projects/ntf_abc123' \
--header 'Authorization: Bearer pf_YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"level": "level_abc123"
}'Response
{ "projectId": "prj_abc123", "level": "muted" }- Scope
- notifications:read
Request
curl --request GET \
--url 'https://projectfeed.app/api/v1/notifications/preferences' \
--header 'Authorization: Bearer pf_YOUR_API_KEY'Response
{
"emailNewComment": true,
"emailNewReaction": false,
"emailNewPost": false,
"emailMention": true,
"emailDigest": "daily",
"emailTeamActivity": true,
"emailTasks": true,
"pushNewComment": false,
"pushNewReaction": false,
"pushNewPost": false,
"pushMention": true,
"pushTeamActivity": false,
"pushTasks": false,
"pushAssignments": true,
"pushHandoffs": true,
"inAppNewComment": true,
"inAppNewReaction": true,
"inAppNewPost": true,
"inAppMention": true,
"inAppTeamActivity": true,
"inAppTasks": true,
"inAppSoundEnabled": false,
"inAppTabIndicatorEnabled": true,
"globalMute": false,
"quietHoursEnabled": false,
"chatNewPost": true,
"chatNewComment": true,
"chatNewReaction": false,
"chatMention": true,
"chatReviewFeedback": true,
"chatDigest": "none",
"chatPlatformPreference": "both",
"chatQuietHoursEnabled": false,
"emailAssignments": true,
"inAppAssignments": true,
"emailHandoffs": true,
"inAppHandoffs": true,
"emailDiscussions": true,
"pushDiscussions": false,
"inAppDiscussions": true,
"updatedAt": 0,
"chatIntegrations": {
"slack": {
"connected": false,
"username": null
},
"discord": {
"connected": false,
"username": null
},
"truncated": false
}
}- Scope
- notifications:write
Body parameters
expectedUpdatedAtnumberThe updatedAt you last read. If the preferences have changed since, the request returns 412 and nothing is written. An If-Match header with the ETag does the same.
resetToAccountbooleanSend true without other fields to remove this workspace override and follow account defaults
emailNewCommentbooleanEmail on new comments
emailNewReactionbooleanEmail on new reactions
emailNewPostbooleanEmail on new posts
emailMentionbooleanEmail on mentions
emailDigeststringRoutine email cadence: daily, weekly, or never for individual emails
emailTeamActivitybooleanEmail on team activity
emailTasksbooleanEmail on task status changes and replies
emailAssignmentsbooleanEmail on task assignments and assigned doc comments
emailHandoffsbooleanEmail on handoff approvals, questions, and results. Follows emailTasks until set
emailDiscussionsbooleanEmail on discussion messages and replies. Follows emailNewComment until set
pushNewCommentbooleanPush on new comments
pushNewReactionbooleanPush on new reactions
pushNewPostbooleanPush on new posts
pushMentionbooleanPush on mentions
pushTeamActivitybooleanPush on team activity
pushTasksbooleanPush on task status changes and routine handoff updates
pushAssignmentsbooleanPush on task assignments and assigned doc comments
pushHandoffsbooleanPush on handoff approval requests, questions, and results awaiting review. On for new accounts; older saved preferences follow pushTasks until set
pushDiscussionsbooleanPush on discussion messages and replies. Follows pushNewComment until set
inAppNewCommentbooleanIn-app on new comments
inAppNewReactionbooleanIn-app on new reactions
inAppNewPostbooleanIn-app on new posts
inAppMentionbooleanIn-app on mentions
inAppTeamActivitybooleanIn-app on team activity
inAppTasksbooleanIn-app on task status changes and replies
inAppAssignmentsbooleanIn-app on task assignments and assigned doc comments
inAppHandoffsbooleanIn-app on handoff approvals, questions, and results. Follows inAppTasks until set
inAppDiscussionsbooleanIn-app on discussion messages and replies. Follows inAppNewComment until set
inAppSoundEnabledbooleanPlay a sound for new in-app notifications
inAppTabIndicatorEnabledbooleanShow unread activity in the browser tab
chatNewPostbooleanConnected-chat notifications on new posts
chatNewCommentbooleanConnected-chat notifications on comments
chatNewReactionbooleanConnected-chat notifications on reactions
chatMentionbooleanConnected-chat notifications on mentions
chatReviewFeedbackbooleanConnected-chat notifications on review feedback
chatDigeststringnone, daily, or weekly
chatPlatformPreferencestringslack, discord, or both
chatQuietHoursEnabledbooleanApply quiet hours to connected-chat delivery
chatAnnotationEnabledbooleanConnected-chat annotation notifications
globalMutebooleanPause email and push while retaining inbox activity
quietHoursEnabledbooleanEnable quiet hours
quietHoursStartstringQuiet hours start time (HH:MM)
quietHoursEndstringQuiet hours end time (HH:MM)
quietHoursTimezonestringQuiet hours timezone, such as America/New_York
Request
curl --request PATCH \
--url 'https://projectfeed.app/api/v1/notifications/preferences' \
--header 'Authorization: Bearer pf_YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"emailDigest": "weekly",
"quietHoursEnabled": true
}'Response
{
"_id": "ntp_abc123",
"_creationTime": 1779600000000,
"userId": "usr_abc123",
"organizationId": "ws_abc123",
"emailNewComment": true,
"emailNewReaction": false,
"emailDigest": "weekly",
"globalMute": false,
"quietHoursEnabled": true,
"quietHoursStart": "22:00",
"quietHoursEnd": "08:00",
"quietHoursTimezone": "America/New_York",
"createdAt": 1779600000000,
"updatedAt": 1779680000000
}Pagination
Use offset and limit to page through visible notifications. If hidden notifications stop a page before it is full, the response still returns the visible items collected so far, truncated true, and a nextCursor. Pass nextCursor until hasMore is false instead of increasing offset. Pages can be empty when older notifications are hidden. Actor objects carry several avatar fields; use image. See API conventions for cursors.
Workspace and account preferences
/api/v1/notifications/preferences works on one workspace and accepts a workspace API key or a personal API token. Saving there creates a workspace override of your account defaults.
/api/v1/me/notification-preferences works on your account defaults and needs a personal API token. It also lists your workspace overrides, read-only. It accepts more fields than the workspace endpoint: sound, tab indicator, and the chat settings.
Preferences are flat fields named by channel (email, push, inApp) and event, such as pushMention. globalMute and the quietHours fields apply to every channel.