Notifications API

7 endpoints, generated from packages/core/openapi/v1.snapshot.json (OpenAPI 3.1.0, contract version 1.0). Conventions for lists, errors, money and authentication are on the API conventions page.

GET/api/v1/notifications

List my notifications

Every response carries `cursor`, the position of the newest item in this view. Pass it back as `since` to get only newer notifications, oldest first (`sort` is then ignored); `cursor` then points at the last item returned, so a client pages forward with it until `items` is empty. `cursor` is null only when there is nothing to point at.

Access

Any signed-in member (own data only)

Parameters

Name	In	Type	Required
page	query	integer	no
pageSize	query	integer	no
sort	query	enum	no
unread	query	enum	no
since A `cursor` from an earlier response.	query	string	no

Responses

200 Success. object

• itemsarray of objectrequired

  • idstring (uuid)required
  • kindstringrequired
  • categorystringrequired
  • titlestringrequired
  • bodystring | nullrequired
  • linkstringrequired
  • createdAtstring (date-time)required
  • readAtstring (date-time) or nullrequired
• pageintegerrequired

  min -9007199254740991

• pageSizeintegerrequired

  min -9007199254740991

• totalintegerrequired

  min -9007199254740991

• unreadintegerrequired

  min -9007199254740991

• cursorstring | nullrequired

  Opaque. Pass as `since` for newer notifications.

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 mfa_enrolment_required

POST/api/v1/notifications/{id}/read

Mark a notification read

Access

Any signed-in member (own data only)

Parameters

Name	In	Type	Required
id	path	string (uuid)	yes

Responses

204 No content.

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, mfa_enrolment_required
• 404 not_found

GET/api/v1/notifications/delivery

Email delivery status

Whether email is configured, outbox counts, and emails that failed after every retry.

Access

Permission notification_delivery:read

Responses

200 Success. object

• emailConfiguredbooleanrequired
• setupHelpstring | nullrequired
• countsobjectrequired

  • queuedintegerrequired

    min -9007199254740991

  • sentintegerrequired

    min -9007199254740991

  • failedintegerrequired

    min -9007199254740991

  • suppressedintegerrequired

    min -9007199254740991

• failedarray of objectrequired

  • idstring (uuid)required
  • tostringrequired
  • kindstringrequired
  • attemptsintegerrequired

    min -9007199254740991

  • lastErrorstring | nullrequired
  • createdAtstring (date-time)required

• 401 session_expired, session_revoked, unauthenticated
• 403 forbidden, mfa_enrolment_required

GET/api/v1/notifications/preferences

Get my email preferences

Access

Any signed-in member (own data only)

Responses

200 Success. object

• emailConfiguredbooleanrequired
• categoriesarray of objectrequired

  • categoryenumrequired

    one of "approvals", "requests", "reminders", "updates", "security"

  • labelstringrequired
  • descriptionstringrequired
  • emailEnabledbooleanrequired
  • lockedbooleanrequired

• 401 session_expired, session_revoked, unauthenticated
• 403 mfa_enrolment_required

PUT/api/v1/notifications/preferences

Set my email preferences

Per category; security emails cannot be turned off.

Access

Any signed-in member (own data only)

Request body

application/json, object, required

• emailobjectrequired

Responses

200 Success. object

• updatedintegerrequired

  min -9007199254740991

• 400 validation_failed
• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, mfa_enrolment_required

POST/api/v1/notifications/read-all

Mark all my notifications read

Access

Any signed-in member (own data only)

Responses

200 Success. object

• updatedintegerrequired

  min -9007199254740991

• 401 session_expired, session_revoked, unauthenticated
• 403 csrf_rejected, mfa_enrolment_required

GET/api/v1/notifications/unread-count

Count my unread notifications

Cheap enough to poll; the top bar shows it.

Access

Any signed-in member (own data only)

Responses

200 Success. object

• unreadintegerrequired

  min -9007199254740991

• 401 session_expired, session_revoked, unauthenticated
• 403 mfa_enrolment_required