Notifications
- GET
/rest/v1.0/projects/{project_id}/notificationsList the caller's notification inbox - POST
/rest/v1.0/projects/{project_id}/notifications/mark_readMark notifications in the caller's inbox read - GET
/rest/v1.0/projects/{project_id}/notifications/preferencesGet the caller's notification preferences - PATCH
/rest/v1.0/projects/{project_id}/notifications/preferencesUpdate the caller's notification preferences - GET
/rest/v1.0/projects/{project_id}/notifications/settingsList a project's notification recipient rules for a tool - POST
/rest/v1.0/projects/{project_id}/notifications/settingsCreate or update a project notification recipient rule - PATCH
/rest/v1.0/projects/{project_id}/notifications/settings/{id}Enable or disable a project notification recipient rule - DELETE
/rest/v1.0/projects/{project_id}/notifications/settings/{id}Delete a project notification recipient rule
/rest/v1.0/projects/{project_id}/notificationsList the caller's notification inbox
Requires notifications:read. The project id must identify a project in the caller's company. Returns the caller's own currently visible inbox across projects and company-wide events, newest first, with summaries and deep links. Source record operations require their own tool scopes. The project in the path validates company access and leaves inbox results recipient-wide.
Parameters
- project_idintegerpathrequiredProject id in the caller's company. Settings are scoped to this project. The inbox and preferences use the caller's identity.
- pageintegerqueryOne-based page number.
- per_pageintegerqueryMaximum items in a page.
- unreadbooleanquerySet to true to show only unread items.
- filters[read]booleanquerySet to false to show only unread items. True leaves results unfiltered.
Response · 200 · object[]
- idintegerrequired
- project_idintegerrequiredProject id, or zero for a company-wide activity.
- company_idintegerrequired
- recipient_idintegerrequired
- item_typestringrequired
- item_type_labelstringrequired
- item_idintegerrequired
- eventstringrequired
- event_labelstringrequired
- summarystringrequired
- urlstringrequiredThe in-app path to the activity.
- readbooleanrequired
- read_atstring (date-time) | nullrequired
- actorobject | nullrequired
- actor.idintegerrequired
- actor.loginstringrequired
- actor.namestringrequired
- actor.localestringrequired
- created_atstring (date-time)required
Errors
400401403404429500503
Example request
curl -X GET "https://app.os.construction/rest/v1.0/projects/1/notifications" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/projects/{project_id}/notifications/mark_readMark notifications in the caller's inbox read
Requires notifications:write. The project id must identify a project in the caller's company. Marks currently visible notifications read for the caller across projects. Supply ids or all: true. The all option takes precedence if both are supplied.
Parameters
- project_idintegerpathrequiredProject id in the caller's company. Settings are scoped to this project. The inbox and preferences use the caller's identity.
- Idempotency-KeystringheaderOptional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.
Request body
- allbooleanrequired
Response · 200 · object
- updatedintegerrequired
- unreadintegerrequired
Errors
400401403404429500503
Example request
curl -X POST "https://app.os.construction/rest/v1.0/projects/1/notifications/mark_read" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"all": true
}'/rest/v1.0/projects/{project_id}/notifications/preferencesGet the caller's notification preferences
Requires notifications:read. The project id must identify a project in the caller's company. Returns user-wide notification channels for each displayed event and the caller's digest cadence. Unsaved channels default to on and unsaved cadence defaults to off.
Parameters
- project_idintegerpathrequiredProject id in the caller's company. Settings are scoped to this project. The inbox and preferences use the caller's identity.
Response · 200 · object
- preferencesobject[]required
- preferences[].eventstringrequiredOne of: assigned, status_changed, commented, replied, mentioned, overdue, published, insight_opened, automation.
- preferences[].event_labelstringrequired
- preferences[].in_appbooleanrequired
- preferences[].emailbooleanrequired
- digest_frequencystringrequiredOne of: off, daily, weekly.
Errors
401403404429500503
Example request
curl -X GET "https://app.os.construction/rest/v1.0/projects/1/notifications/preferences" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/projects/{project_id}/notifications/preferencesUpdate the caller's notification preferences
Requires notifications:write. The project id must identify a project in the caller's company. Saves the caller's user-wide preferences for future delivery. A supplied event row sets both channel flags, with omitted flags defaulting to true. Omitted events and cadence retain their existing values. Updating the cadence schedules or cancels the caller's future digests.
Parameters
- project_idintegerpathrequiredProject id in the caller's company. Settings are scoped to this project. The inbox and preferences use the caller's identity.
- Idempotency-KeystringheaderOptional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.
Request body
- notification_preferencesobject
- notification_preferences.preferencesobject[]
- notification_preferences.preferences[].eventstringrequiredThe event key. Use an event from the preferences grid for a row reflected in the response.
- notification_preferences.preferences[].in_appboolean
- notification_preferences.preferences[].emailboolean
- notification_preferences.digest_frequencystring | nullUse off, daily, or weekly. Other non-null values are interpreted as off.
Response · 200 · object
- preferencesobject[]required
- preferences[].eventstringrequiredOne of: assigned, status_changed, commented, replied, mentioned, overdue, published, insight_opened, automation.
- preferences[].event_labelstringrequired
- preferences[].in_appbooleanrequired
- preferences[].emailbooleanrequired
- digest_frequencystringrequiredOne of: off, daily, weekly.
Errors
401403404429500503
Example request
curl -X PATCH "https://app.os.construction/rest/v1.0/projects/1/notifications/preferences" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"notification_preferences": {}
}'/rest/v1.0/projects/{project_id}/notifications/settingsList a project's notification recipient rules for a tool
Requires notifications:read and Notifications admin permission on the specified project. Returns enabled and disabled rules for the given tool, sorted by event and then by row id.
Parameters
- project_idintegerpathrequiredProject id in the caller's company. Settings are scoped to this project. The inbox and preferences use the caller's identity.
- toolstringqueryrequiredTool slug whose notification recipient rules to list.
Response · 200 · object[]
- idintegerrequired
- project_idintegerrequired
- company_idintegerrequired
- tool_slugstringrequired
- eventstringrequired
- event_labelstringrequired
- recipient_typestringrequiredOne of: role, user.
- recipient_refstringrequired
- enabledbooleanrequired
Errors
400401403404429500503
Example request
curl -X GET "https://app.os.construction/rest/v1.0/projects/1/notifications/settings" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN"/rest/v1.0/projects/{project_id}/notifications/settingsCreate or update a project notification recipient rule
Requires notifications:write and Notifications admin permission on the specified project. Upserts a rule keyed by project, tool slug, event, recipient type, and recipient reference. An existing rule receives the new enabled value, which defaults to true. This affects recipients added by the rule on future matching events, subject to source access and their own channel preferences. Saving the rule does not send a notification.
Parameters
- project_idintegerpathrequiredProject id in the caller's company. Settings are scoped to this project. The inbox and preferences use the caller's identity.
- Idempotency-KeystringheaderOptional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.
Request body
- notification_settingobjectrequired
- notification_setting.tool_slugstringrequiredTool slug used by the matching event.
- notification_setting.eventstringrequiredEvent key emitted by the tool.
- notification_setting.recipient_typestringSelect a permission template with role or a user with user. One of: role, user.
- notification_setting.recipient_refstring | integerrequiredId of the selected permission template or user. The rule stores this as a string.
- notification_setting.enabledboolean
Response · 201 · object
- idintegerrequired
- project_idintegerrequired
- company_idintegerrequired
- tool_slugstringrequired
- eventstringrequired
- event_labelstringrequired
- recipient_typestringrequiredOne of: role, user.
- recipient_refstringrequired
- enabledbooleanrequired
Errors
400401403404429500503
Example request
curl -X POST "https://app.os.construction/rest/v1.0/projects/1/notifications/settings" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"notification_setting": {
"tool_slug": "string",
"event": "string",
"recipient_ref": "string"
}
}'/rest/v1.0/projects/{project_id}/notifications/settings/{id}Enable or disable a project notification recipient rule
Requires notifications:write and Notifications admin permission on the specified project. This affects recipients added by the rule on future matching events, subject to source access and their own channel preferences. Saving the rule does not send a notification.
Parameters
- project_idintegerpathrequiredProject id in the caller's company. Settings are scoped to this project. The inbox and preferences use the caller's identity.
- idintegerpathrequiredNotification recipient rule id in the specified project.
- Idempotency-KeystringheaderOptional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.
Request body
- notification_settingobjectrequired
- notification_setting.enabledbooleanrequired
Response · 200 · object
- idintegerrequired
- enabledbooleanrequired
Errors
400401403404429500503
Example request
curl -X PATCH "https://app.os.construction/rest/v1.0/projects/1/notifications/settings/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"notification_setting": {
"enabled": true
}
}'/rest/v1.0/projects/{project_id}/notifications/settings/{id}Delete a project notification recipient rule
Requires notifications:write and Notifications admin permission on the specified project. Removes the rule's contribution to future matching events. The response has an empty body.
Parameters
- project_idintegerpathrequiredProject id in the caller's company. Settings are scoped to this project. The inbox and preferences use the caller's identity.
- idintegerpathrequiredNotification recipient rule id in the specified project.
- Idempotency-KeystringheaderOptional. A unique key (1-255 visible ASCII characters, e.g. a UUID) that makes a retry safe. The first request with a key runs; a 2xx response is stored for 24 hours and a retry with the same key, token and path gets that response again with `Idempotent-Replayed: true`. The same key with a different request returns 422; while the first request is still running, 409. A non-2xx response releases the key.
Response · 204
No response body.
Errors
401403404429500503
Example request
curl -X DELETE "https://app.os.construction/rest/v1.0/projects/1/notifications/settings/1" \
-H "Authorization: Bearer $OS_ACCESS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)"