Skip to content

Notifications API reference

Notification API route handlers.

delete_notification

delete_notification(request, notification_id, token_user_id, db)

Delete one of the caller's notifications. 404 when the caller has no such notification.

Source code in backend/app/modules/notifications/router.py
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
@router.delete(
    "/{notification_id}",
    response_model=None,
    status_code=status.HTTP_204_NO_CONTENT,
    dependencies=[Security(auth_dependencies.check_scopes, scopes=["notifications:write"])],
)
@core_rate_limit.limiter.limit(core_rate_limit.WRITE)
def delete_notification(
    request: Request,
    notification_id: core_dependencies.UuidId,
    token_user_id: auth_dependencies.CurrentUserId,
    db: core_dependencies.DbSession,
) -> None:
    """Delete one of the caller's notifications. `404` when the caller has no such notification."""
    notifications_service.delete_notification(notification_id, token_user_id, db)

mark_notification_as_read

mark_notification_as_read(request, notification_id, token_user_id, db)

Mark a specific notification as read.

Parameters:

Name Type Description Default
request Request

The incoming request, used by the rate limiter.

required
notification_id UuidId

ID of the notification to mark as read.

required
token_user_id CurrentUserId

ID of the user from the access token.

required
db DbSession

Database session dependency.

required

Returns:

Type Description
None

None.

Source code in backend/app/modules/notifications/router.py
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
@router.post(
    "/{notification_id}/read",
    response_model=None,
    status_code=status.HTTP_204_NO_CONTENT,
    dependencies=[Security(auth_dependencies.check_scopes, scopes=["notifications:write"])],
)
@core_rate_limit.limiter.limit(core_rate_limit.WRITE)
def mark_notification_as_read(
    request: Request,
    notification_id: core_dependencies.UuidId,
    token_user_id: auth_dependencies.CurrentUserId,
    db: core_dependencies.DbSession,
) -> None:
    """Mark a specific notification as read.

    Args:
        request: The incoming request, used by the rate limiter.
        notification_id: ID of the notification to mark as read.
        token_user_id: ID of the user from the access token.
        db: Database session dependency.

    Returns:
        None.
    """
    notifications_service.mark_notification_as_read(notification_id, token_user_id, db)

mark_notifications_as_read

mark_notifications_as_read(request, token_user_id, db, body=None)

Mark notifications as read.

With {"ids": [...]} (at most 100) only those are marked; an id that is not the caller's is skipped, so the answer does not reveal which ids exist. Without a body every unread notification of the caller is marked.

Source code in backend/app/modules/notifications/router.py
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
@router.post(
    "/read",
    response_model=None,
    status_code=status.HTTP_204_NO_CONTENT,
    dependencies=[Security(auth_dependencies.check_scopes, scopes=["notifications:write"])],
)
@core_rate_limit.limiter.limit(core_rate_limit.WRITE)
def mark_notifications_as_read(
    request: Request,
    token_user_id: auth_dependencies.CurrentUserId,
    db: core_dependencies.DbSession,
    body: notifications_schema.NotificationsMarkRead | None = None,
) -> None:
    """Mark notifications as read.

    With `{"ids": [...]}` (at most 100) only those are marked; an id that is not the caller's is skipped, so the
    answer does not reveal which ids exist. Without a body every unread notification of the caller is marked.
    """
    if body is None:
        notifications_service.mark_all_notifications_as_read(token_user_id, db)
    else:
        notifications_service.mark_notifications_as_read(body.ids, token_user_id, db)

read_notifications_by_id

read_notifications_by_id(notification_id, token_user_id, db)

Retrieve a notification by ID for the user.

Parameters:

Name Type Description Default
notification_id UuidId

Unique ID of the notification.

required
token_user_id CurrentUserId

ID of the user from the access token.

required
db DbSession

Database session dependency.

required

Returns:

Type Description
NotificationRead

The notification.

Source code in backend/app/modules/notifications/router.py
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
@router.get(
    "/{notification_id}",
    response_model=notifications_schema.NotificationRead,
    dependencies=[Security(auth_dependencies.check_scopes, scopes=["notifications:read"])],
)
def read_notifications_by_id(
    notification_id: core_dependencies.UuidId,
    token_user_id: auth_dependencies.CurrentUserId,
    db: core_dependencies.DbSession,
) -> notifications_schema.NotificationRead:
    """Retrieve a notification by ID for the user.

    Args:
        notification_id: Unique ID of the notification.
        token_user_id: ID of the user from the access token.
        db: Database session dependency.

    Returns:
        The notification.
    """
    return notifications_service.get_notification(notification_id, token_user_id, db)

read_notifications_user_pagination

read_notifications_user_pagination(token_user_id, db, cursor=None, num_records=None, unread_only=False)

List a keyset slice of the caller's notifications, newest first.

Pass the next_cursor of a slice as cursor to get the following one; it is null on the last slice. unread_only=true keeps only the notifications that have not been read, and must stay the same across the slices of one walk.

Source code in backend/app/modules/notifications/router.py
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
@router.get(
    "",
    response_model=notifications_schema.NotificationPage,
    dependencies=[Security(auth_dependencies.check_scopes, scopes=["notifications:read"])],
)
def read_notifications_user_pagination(
    token_user_id: auth_dependencies.CurrentUserId,
    db: core_dependencies.DbSession,
    cursor: Annotated[str | None, Query()] = None,
    num_records: Annotated[int | None, Query(ge=1, le=core_pagination.MAX_NUM_RECORDS)] = None,
    unread_only: Annotated[bool, Query()] = False,
) -> notifications_schema.NotificationPage:
    """List a keyset slice of the caller's notifications, newest first.

    Pass the `next_cursor` of a slice as `cursor` to get the following one; it is `null` on the last slice.
    `unread_only=true` keeps only the notifications that have not been read, and must stay the same across the
    slices of one walk.
    """
    return notifications_service.list_notifications(
        token_user_id,
        db,
        cursor=cursor,
        num_records=num_records or core_pagination.DEFAULT_NUM_RECORDS,
        unread_only=unread_only,
    )

read_unread_notifications_count

read_unread_notifications_count(token_user_id, db)

Return how many of the caller's notifications have not been read.

Source code in backend/app/modules/notifications/router.py
17
18
19
20
21
22
23
24
25
26
27
28
29
@router.get(
    "/unread-count",
    response_model=notifications_schema.NotificationUnreadCount,
    dependencies=[Security(auth_dependencies.check_scopes, scopes=["notifications:read"])],
)
def read_unread_notifications_count(
    token_user_id: auth_dependencies.CurrentUserId,
    db: core_dependencies.DbSession,
) -> notifications_schema.NotificationUnreadCount:
    """Return how many of the caller's notifications have not been read."""
    return notifications_schema.NotificationUnreadCount(
        count=notifications_service.count_unread_notifications(token_user_id, db)
    )

Pydantic schemas for notification entities.

AccountNoticeNotificationRead

Bases: _NotificationReadBase

A Garmin-unlinked or Strava-data-deleted notification, which carries no options.

Source code in backend/app/modules/notifications/schema.py
223
224
225
226
227
228
229
class AccountNoticeNotificationRead(_NotificationReadBase):
    """A Garmin-unlinked or Strava-data-deleted notification, which carries no options."""

    type: Literal[_Type.GARMIN_TOKEN_EXPIRED, _Type.STRAVA_DATA_DELETED] = Field(
        ..., description="Type of the notification"
    )
    options: NoNotificationOptions

AccountSecurityChangedNotificationOptions

Bases: NotificationOptions

Options of the notification that a security setting of the account changed.

Attributes:

Name Type Description
change StrictStr

The kind of change.

idp_id UUID | None

The identity provider concerned, for an unlink.

idp_name StrictStr | None

Its name, or None when it was deleted since.

access_type StrictStr | None

The access type the account now has, for a role change.

backup_codes_remaining StrictInt | None

How many unused backup codes are left, for a backup code that was used.

Source code in backend/app/modules/notifications/schema.py
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
class AccountSecurityChangedNotificationOptions(NotificationOptions):
    """Options of the notification that a security setting of the account changed.

    Attributes:
        change: The kind of change.
        idp_id: The identity provider concerned, for an unlink.
        idp_name: Its name, or None when it was deleted since.
        access_type: The access type the account now has, for a role change.
        backup_codes_remaining: How many unused backup codes are left, for a backup code that was used.
    """

    change: StrictStr = Field(..., description="Kind of security change")
    idp_id: uuid.UUID | None = Field(default=None, description="ID of the identity provider concerned")
    idp_name: StrictStr | None = Field(default=None, description="Name of the provider, when it still exists")
    access_type: StrictStr | None = Field(default=None, description="Access type the account now has")
    backup_codes_remaining: StrictInt | None = Field(default=None, description="Unused backup codes left")

AccountSecurityChangedNotificationRead

Bases: _NotificationReadBase

A security-setting-changed notification.

Source code in backend/app/modules/notifications/schema.py
246
247
248
249
250
class AccountSecurityChangedNotificationRead(_NotificationReadBase):
    """A security-setting-changed notification."""

    type: Literal[_Type.ACCOUNT_SECURITY_CHANGED] = Field(..., description="Type of the notification")
    options: AccountSecurityChangedNotificationOptions

ActivityNotificationOptions

Bases: NotificationOptions

Options of a new or duplicate activity notification.

Attributes:

Name Type Description
activity_id UUID

The stored activity.

Source code in backend/app/modules/notifications/schema.py
82
83
84
85
86
87
88
89
class ActivityNotificationOptions(NotificationOptions):
    """Options of a new or duplicate activity notification.

    Attributes:
        activity_id: The stored activity.
    """

    activity_id: uuid.UUID = Field(..., description="ID of the activity the notification is about")

ActivityNotificationRead

Bases: _NotificationReadBase

A new-activity or duplicate-activity notification.

Source code in backend/app/modules/notifications/schema.py
204
205
206
207
208
class ActivityNotificationRead(_NotificationReadBase):
    """A new-activity or duplicate-activity notification."""

    type: Literal[_Type.NEW_ACTIVITY, _Type.DUPLICATE_ACTIVITY] = Field(..., description="Type of the notification")
    options: ActivityNotificationOptions

IdpLinkedNotificationOptions

Bases: NotificationOptions

Options of the notification that a sign-in provider was linked.

Attributes:

Name Type Description
idp_id UUID

The linked identity provider.

idp_name StrictStr | None

Its name, or None when it was deleted since.

Source code in backend/app/modules/notifications/schema.py
117
118
119
120
121
122
123
124
125
126
class IdpLinkedNotificationOptions(NotificationOptions):
    """Options of the notification that a sign-in provider was linked.

    Attributes:
        idp_id: The linked identity provider.
        idp_name: Its name, or None when it was deleted since.
    """

    idp_id: uuid.UUID = Field(..., description="ID of the linked identity provider")
    idp_name: StrictStr | None = Field(default=None, description="Name of the provider, when it still exists")

IdpLinkedNotificationRead

Bases: _NotificationReadBase

A sign-in-provider-linked notification.

Source code in backend/app/modules/notifications/schema.py
239
240
241
242
243
class IdpLinkedNotificationRead(_NotificationReadBase):
    """A sign-in-provider-linked notification."""

    type: Literal[_Type.IDP_LINKED] = Field(..., description="Type of the notification")
    options: IdpLinkedNotificationOptions

NewDeviceSignInNotificationOptions

Bases: NotificationOptions

Options of the notification that the account was signed in to from a new device.

Attributes:

Name Type Description
browser StrictStr

The browser family of the sign-in.

operating_system StrictStr

The operating-system family of the sign-in.

ip_address StrictStr

The client address of the sign-in.

Source code in backend/app/modules/notifications/schema.py
147
148
149
150
151
152
153
154
155
156
157
158
class NewDeviceSignInNotificationOptions(NotificationOptions):
    """Options of the notification that the account was signed in to from a new device.

    Attributes:
        browser: The browser family of the sign-in.
        operating_system: The operating-system family of the sign-in.
        ip_address: The client address of the sign-in.
    """

    browser: StrictStr = Field(..., description="Browser family of the sign-in")
    operating_system: StrictStr = Field(..., description="Operating-system family of the sign-in")
    ip_address: StrictStr = Field(..., description="Client address of the sign-in")

NewDeviceSignInNotificationRead

Bases: _NotificationReadBase

A new-device-sign-in notification.

Source code in backend/app/modules/notifications/schema.py
253
254
255
256
257
class NewDeviceSignInNotificationRead(_NotificationReadBase):
    """A new-device-sign-in notification."""

    type: Literal[_Type.NEW_DEVICE_SIGN_IN] = Field(..., description="Type of the notification")
    options: NewDeviceSignInNotificationOptions

NoNotificationOptions

Bases: NotificationOptions

The options of a notification that carries none.

Source code in backend/app/modules/notifications/schema.py
78
79
class NoNotificationOptions(NotificationOptions):
    """The options of a notification that carries none."""

NotificationBase

Bases: BaseModel

Base schema for notification data.

Attributes:

Name Type Description
options dict[str, Any] | None

Additional metadata for the notification.

Source code in backend/app/modules/notifications/schema.py
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
class NotificationBase(BaseModel):
    """Base schema for notification data.

    Attributes:
        options: Additional metadata for the notification.
    """

    options: dict[str, Any] | None = Field(
        default=None,
        description="Additional notification metadata",
    )

    model_config = ConfigDict(
        from_attributes=True,
        extra="forbid",
        validate_assignment=True,
    )

NotificationCreate

Bases: NotificationBase

Schema for creating a notification record.

Attributes:

Name Type Description
type NotificationType

Type of the notification.

user_id UUID

FK to user.

source_event_id str | None

Durable event ID for idempotent creation.

Source code in backend/app/modules/notifications/schema.py
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
class NotificationCreate(NotificationBase):
    """Schema for creating a notification record.

    Attributes:
        type: Type of the notification.
        user_id: FK to user.
        source_event_id: Durable event ID for idempotent creation.
    """

    type: notifications_constants.NotificationType = Field(
        ...,
        description="Type of the notification",
    )
    user_id: uuid.UUID = Field(
        ...,
        description="FK to user",
    )
    source_event_id: str | None = Field(
        default=None,
        max_length=36,
        description="Durable event ID for idempotent creation",
    )

NotificationOptions

Bases: BaseModel

Base of the options a notification type stores.

Unknown keys are ignored on read, so a row written by an older release still loads.

Source code in backend/app/modules/notifications/schema.py
69
70
71
72
73
74
75
class NotificationOptions(BaseModel):
    """Base of the options a notification type stores.

    Unknown keys are ignored on read, so a row written by an older release still loads.
    """

    model_config = ConfigDict(extra="ignore")

NotificationPage

Bases: CursorPage[NotificationRead]

One keyset slice of the caller's notifications.

The list takes inserts at the head, so offset paging would repeat and skip rows across requests.

Source code in backend/app/modules/notifications/schema.py
273
274
275
276
277
class NotificationPage(core_pagination.CursorPage[NotificationRead]):
    """One keyset slice of the caller's notifications.

    The list takes inserts at the head, so offset paging would repeat and skip rows across requests.
    """

NotificationUnreadCount

Bases: BaseModel

The number of notifications a user has not read.

Attributes:

Name Type Description
count StrictInt

Number of unread notifications.

Source code in backend/app/modules/notifications/schema.py
283
284
285
286
287
288
289
290
291
292
class NotificationUnreadCount(BaseModel):
    """The number of notifications a user has not read.

    Attributes:
        count: Number of unread notifications.
    """

    model_config = ConfigDict(extra="forbid")

    count: StrictInt = Field(..., ge=0, description="Number of unread notifications")

NotificationsMarkRead

Bases: BaseModel

The notifications to mark as read.

Attributes:

Name Type Description
ids list[UUID]

The notifications to mark; each must be one of the caller's.

Source code in backend/app/modules/notifications/schema.py
295
296
297
298
299
300
301
302
303
304
305
306
class NotificationsMarkRead(BaseModel):
    """The notifications to mark as read.

    Attributes:
        ids: The notifications to mark; each must be one of the caller's.
    """

    model_config = ConfigDict(extra="forbid")

    ids: list[uuid.UUID] = Field(
        ..., min_length=1, max_length=MAX_MARK_READ_IDS, description="IDs of the notifications to mark as read"
    )

StravaTokenExpiredNotificationOptions

Bases: NotificationOptions

Options of the notification that a Strava account was unlinked.

Attributes:

Name Type Description
delete_on date | None

The day the Strava data is deleted when Strava access was revoked; absent when the token was only rejected.

Source code in backend/app/modules/notifications/schema.py
106
107
108
109
110
111
112
113
114
class StravaTokenExpiredNotificationOptions(NotificationOptions):
    """Options of the notification that a Strava account was unlinked.

    Attributes:
        delete_on: The day the Strava data is deleted when Strava access was revoked; absent when the token was
            only rejected.
    """

    delete_on: date | None = Field(default=None, description="Day the user's Strava data is deleted")

StravaTokenExpiredNotificationRead

Bases: _NotificationReadBase

A Strava-unlinked notification.

Source code in backend/app/modules/notifications/schema.py
232
233
234
235
236
class StravaTokenExpiredNotificationRead(_NotificationReadBase):
    """A Strava-unlinked notification."""

    type: Literal[_Type.STRAVA_TOKEN_EXPIRED] = Field(..., description="Type of the notification")
    options: StravaTokenExpiredNotificationOptions

UserReferenceNotificationOptions

Bases: NotificationOptions

Options of a notification that names another user.

Attributes:

Name Type Description
user_id UUID

The user the notification names.

user_name StrictStr

That user's name when the notification was created.

user_username StrictStr

That user's username when the notification was created.

Source code in backend/app/modules/notifications/schema.py
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
class UserReferenceNotificationOptions(NotificationOptions):
    """Options of a notification that names another user.

    Attributes:
        user_id: The user the notification names.
        user_name: That user's name when the notification was created.
        user_username: That user's username when the notification was created.
    """

    user_id: uuid.UUID = Field(..., description="ID of the user the notification names")
    user_name: StrictStr = Field(..., description="Name of that user when the notification was created")
    user_username: StrictStr = Field(..., description="Username of that user when the notification was created")

UserReferenceNotificationRead

Bases: _NotificationReadBase

A follow-request, follow-accepted, sign-up-approval or admin-promoted notification, which names a user.

Source code in backend/app/modules/notifications/schema.py
211
212
213
214
215
216
217
218
219
220
class UserReferenceNotificationRead(_NotificationReadBase):
    """A follow-request, follow-accepted, sign-up-approval or admin-promoted notification, which names a user."""

    type: Literal[
        _Type.NEW_FOLLOWER_REQUEST,
        _Type.NEW_FOLLOWER_REQUEST_ACCEPTED,
        _Type.ADMIN_NEW_SIGN_UP_APPROVAL_REQUEST,
        _Type.ADMIN_USER_PROMOTED,
    ] = Field(..., description="Type of the notification")
    options: UserReferenceNotificationOptions