Esc

↑↓ move↵ openIndex · Pagefind
REST reference · Core Tools

Notifications

8 endpoints8 implementedAll modules →
  1. GET /rest/v1.0/projects/{project_id}/notificationsList the caller's notification inbox
  2. POST /rest/v1.0/projects/{project_id}/notifications/mark_readMark notifications in the caller's inbox read
  3. GET /rest/v1.0/projects/{project_id}/notifications/preferencesGet the caller's notification preferences
  4. PATCH /rest/v1.0/projects/{project_id}/notifications/preferencesUpdate the caller's notification preferences
  5. GET /rest/v1.0/projects/{project_id}/notifications/settingsList a project's notification recipient rules for a tool
  6. POST /rest/v1.0/projects/{project_id}/notifications/settingsCreate or update a project notification recipient rule
  7. PATCH /rest/v1.0/projects/{project_id}/notifications/settings/{id}Enable or disable a project notification recipient rule
  8. DELETE /rest/v1.0/projects/{project_id}/notifications/settings/{id}Delete a project notification recipient rule
GET /rest/v1.0/projects/{project_id}/notifications

List 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.

v1.0Implemented

Parameters

  • project_id
    integerpathrequired
    Project id in the caller's company. Settings are scoped to this project. The inbox and preferences use the caller's identity.
  • page
    integerquery
    One-based page number.
  • per_page
    integerquery
    Maximum items in a page.
  • unread
    booleanquery
    Set to true to show only unread items.
  • filters[read]
    booleanquery
    Set to false to show only unread items. True leaves results unfiltered.

Response · 200 · object[]

  • id
    integerrequired
  • project_id
    integerrequired
    Project id, or zero for a company-wide activity.
  • company_id
    integerrequired
  • recipient_id
    integerrequired
  • item_type
    stringrequired
  • item_type_label
    stringrequired
  • item_id
    integerrequired
  • event
    stringrequired
  • event_label
    stringrequired
  • summary
    stringrequired
  • url
    stringrequired
    The in-app path to the activity.
  • read
    booleanrequired
  • read_at
    string (date-time) | nullrequired
  • actor
    object | nullrequired
  • actor.id
    integerrequired
  • actor.login
    stringrequired
  • actor.name
    stringrequired
  • actor.locale
    stringrequired
  • created_at
    string (date-time)required

Errors

  • 400
  • 401
  • 403
  • 404
  • 429
  • 500
  • 503

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/projects/1/notifications" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
POST /rest/v1.0/projects/{project_id}/notifications/mark_read

Mark 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.

v1.0Implemented

Parameters

  • project_id
    integerpathrequired
    Project id in the caller's company. Settings are scoped to this project. The inbox and preferences use the caller's identity.
  • Idempotency-Key
    stringheader
    Optional. 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

  • all
    booleanrequired

Response · 200 · object

  • updated
    integerrequired
  • unread
    integerrequired

Errors

  • 400
  • 401
  • 403
  • 404
  • 429
  • 500
  • 503

Example request

Generated from the contractcurl
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
}'
GET /rest/v1.0/projects/{project_id}/notifications/preferences

Get 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.

v1.0Implemented

Parameters

  • project_id
    integerpathrequired
    Project id in the caller's company. Settings are scoped to this project. The inbox and preferences use the caller's identity.

Response · 200 · object

  • preferences
    object[]required
  • preferences[].event
    stringrequired
    One of: assigned, status_changed, commented, replied, mentioned, overdue, published, insight_opened, automation.
  • preferences[].event_label
    stringrequired
  • preferences[].in_app
    booleanrequired
  • preferences[].email
    booleanrequired
  • digest_frequency
    stringrequired
    One of: off, daily, weekly.

Errors

  • 401
  • 403
  • 404
  • 429
  • 500
  • 503

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/projects/1/notifications/preferences" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
PATCH /rest/v1.0/projects/{project_id}/notifications/preferences

Update 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.

v1.0Implemented

Parameters

  • project_id
    integerpathrequired
    Project id in the caller's company. Settings are scoped to this project. The inbox and preferences use the caller's identity.
  • Idempotency-Key
    stringheader
    Optional. 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_preferences
    object
  • notification_preferences.preferences
    object[]
  • notification_preferences.preferences[].event
    stringrequired
    The event key. Use an event from the preferences grid for a row reflected in the response.
  • notification_preferences.preferences[].in_app
    boolean
  • notification_preferences.preferences[].email
    boolean
  • notification_preferences.digest_frequency
    string | null
    Use off, daily, or weekly. Other non-null values are interpreted as off.

Response · 200 · object

  • preferences
    object[]required
  • preferences[].event
    stringrequired
    One of: assigned, status_changed, commented, replied, mentioned, overdue, published, insight_opened, automation.
  • preferences[].event_label
    stringrequired
  • preferences[].in_app
    booleanrequired
  • preferences[].email
    booleanrequired
  • digest_frequency
    stringrequired
    One of: off, daily, weekly.

Errors

  • 401
  • 403
  • 404
  • 429
  • 500
  • 503

Example request

Generated from the contractcurl
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": {}
}'
GET /rest/v1.0/projects/{project_id}/notifications/settings

List 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.

v1.0Implemented

Parameters

  • project_id
    integerpathrequired
    Project id in the caller's company. Settings are scoped to this project. The inbox and preferences use the caller's identity.
  • tool
    stringqueryrequired
    Tool slug whose notification recipient rules to list.

Response · 200 · object[]

  • id
    integerrequired
  • project_id
    integerrequired
  • company_id
    integerrequired
  • tool_slug
    stringrequired
  • event
    stringrequired
  • event_label
    stringrequired
  • recipient_type
    stringrequired
    One of: role, user.
  • recipient_ref
    stringrequired
  • enabled
    booleanrequired

Errors

  • 400
  • 401
  • 403
  • 404
  • 429
  • 500
  • 503

Example request

Generated from the contractcurl
curl -X GET "https://app.os.construction/rest/v1.0/projects/1/notifications/settings" \
  -H "Authorization: Bearer $OS_ACCESS_TOKEN"
POST /rest/v1.0/projects/{project_id}/notifications/settings

Create 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.

v1.0Implemented

Parameters

  • project_id
    integerpathrequired
    Project id in the caller's company. Settings are scoped to this project. The inbox and preferences use the caller's identity.
  • Idempotency-Key
    stringheader
    Optional. 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_setting
    objectrequired
  • notification_setting.tool_slug
    stringrequired
    Tool slug used by the matching event.
  • notification_setting.event
    stringrequired
    Event key emitted by the tool.
  • notification_setting.recipient_type
    string
    Select a permission template with role or a user with user. One of: role, user.
  • notification_setting.recipient_ref
    string | integerrequired
    Id of the selected permission template or user. The rule stores this as a string.
  • notification_setting.enabled
    boolean

Response · 201 · object

  • id
    integerrequired
  • project_id
    integerrequired
  • company_id
    integerrequired
  • tool_slug
    stringrequired
  • event
    stringrequired
  • event_label
    stringrequired
  • recipient_type
    stringrequired
    One of: role, user.
  • recipient_ref
    stringrequired
  • enabled
    booleanrequired

Errors

  • 400
  • 401
  • 403
  • 404
  • 429
  • 500
  • 503

Example request

Generated from the contractcurl
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"
  }
}'
PATCH /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.

v1.0Implemented

Parameters

  • project_id
    integerpathrequired
    Project id in the caller's company. Settings are scoped to this project. The inbox and preferences use the caller's identity.
  • id
    integerpathrequired
    Notification recipient rule id in the specified project.
  • Idempotency-Key
    stringheader
    Optional. 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_setting
    objectrequired
  • notification_setting.enabled
    booleanrequired

Response · 200 · object

  • id
    integerrequired
  • enabled
    booleanrequired

Errors

  • 400
  • 401
  • 403
  • 404
  • 429
  • 500
  • 503

Example request

Generated from the contractcurl
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
  }
}'
DELETE /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.

v1.0Implemented

Parameters

  • project_id
    integerpathrequired
    Project id in the caller's company. Settings are scoped to this project. The inbox and preferences use the caller's identity.
  • id
    integerpathrequired
    Notification recipient rule id in the specified project.
  • Idempotency-Key
    stringheader
    Optional. 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

  • 401
  • 403
  • 404
  • 429
  • 500
  • 503

Example request

Generated from the contractcurl
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)"

Ask the OS

Reading this page

Ask anything about this page. Answers use what you're reading as context.

Suggested

    AI · may be imperfect · sample data where shown

    Open file