Notifications

The Notifications API handles in-app notifications for friend requests, messages, and other events.

Notification Types

Type	Description
friend_request	Someone sent you a friend request
friend_accepted	Someone accepted your friend request

Notification States

State	Description
unread	Not yet viewed
read	User has seen it

List Notifications

Get your notifications with pagination.

GET /v1/notifications?limit=50&offset=0
Authorization: Bearer {token}

Query Parameters:

Param	Default	Description
limit	50	Max notifications to return
offset	0	Pagination offset

Response:

{
  "notifications": [
    {
      "id": "123456789",
      "type": "friend_request",
      "data": {
        "from_user_id": 12345,
        "from_display_name": "SomeUser"
      },
      "state": "unread",
      "created_at": 1703520000
    }
  ],
  "total": 15,
  "unread": 3
}

Get Unread Count

Get just the count of unread notifications (for badges).

GET /v1/notifications/unread-count
Authorization: Bearer {token}

Response:

{
  "count": 3
}

Mark as Read

Mark specific notifications or all notifications as read.

POST /v1/notifications/read
Authorization: Bearer {token}

Mark specific notifications:

{
  "notification_ids": ["123", "456", "789"]
}

Mark all as read (empty array or omit field):

{}

Response:

{
  "marked_count": 3
}

Delete Notification

Permanently delete a notification.

DELETE /v1/notifications/{notificationID}
Authorization: Bearer {token}

Response: 204 No Content

Real-time Notifications

New notifications are also pushed via WebSocket. See WebSocket Protocol for the notification event type.