Get notifications via the API

If you have an existing website or application and you would like to encourage discussion on your Discourse forum it can be helpful to display Discourse notifications inside of your application. This guide will show you how to use the Discourse API to fetch notifications for a user and how to mark them as read.

The recommended way of using the API is to have your application make back-end requests to Discourse and then pass that data to the front-end/presentation layer of your application.

Checkout the API Documentation for info on how to use the Discourse API.

Fetching notifications for a user

To get notifications via the API you can make an authenticated GET request to the /notifications endpoint. You can either specify the username you are fetching notifications for in the Api-Username header or as a query parameter: /notifications?username=<username>.

Example request

curl -X GET "http://localhost:8080/notifications.json?username=blake.erickson" \ 
-H "Api-Key: e81c4022f148c872a98fb38dac1d9619c7f5b245b42ba98fa467968bbed7551e" \ 
-H "Api-Username: system"

This will return the following the JSON response

  "notifications": [
      "id": 3,
      "notification_type": 12,
      "read": true,
      "created_at": "2019-06-17T20:26:05.670Z",
      "post_number": null,
      "topic_id": null,
      "slug": null,
      "data": {
        "badge_id": 41,
        "badge_name": "First Emoji",
        "badge_slug": "first-emoji",
        "badge_title": false,
        "username": "blake"
      "id": 2,
      "notification_type": 6,
      "read": true,
      "created_at": "2019-06-17T20:26:04.305Z",
      "post_number": 1,
      "topic_id": 10,
      "fancy_title": "Greetings!",
      "slug": "greetings",
      "data": {
        "topic_title": "Greetings!",
        "original_post_id": 14,
        "original_post_type": 1,
        "original_username": "discobot",
        "revision_number": null,
        "display_username": "discobot"
  "total_rows_notifications": 2,
  "seen_notification_id": 3,
  "load_more_notifications": "/notifications?offset=60&username=blake"

This returns a notification array. If you are interesting in only showing unread notifications you will need to only grab notifications marked as "read": false from the array.

You can visit this page for a listing of notification types. For example notification type: 12 maps to “granted_badge”.

Marking notifications as read

Now that you have fetched a user’s notifications you can mark them as read by sending a PUT request to /notifications/mark-read with the id of the notification in the request body and by specifying the username in the request header.

Example request

curl -X PUT "http://localhost:8080/notifications/mark-read" \ 
-H "Api-Key: e81c4022f148c872a98fb38dac1d9619c7f5b245b42ba98fa467968bbed7551e" \
-H "Api-Username: blake.erickson" \
-F "id=4"

You can also leave off the notification id and it will mark all notifications for that user as read.

This will return a simple “OK” JSON response:

  "success": "OK"

HI @blake
Thank you for the great instruction!
One question, there is a light blue bubble notifications on avatar when I get notification_type NOT 6… after I clicked on avatar, the bubble disappeard… and notifications.json has no change. How can I tell from notifications.js which one is not in light blue bubble anymore ?


Oh that will be useful to play with Discourse topics and Gitlab issues / commits / merge requests / etc.

@blake I have the same question. I want to mirror the notification badge counter that displays in Discourse in my own site - that way the user can see when there are new notifications, click through to discourse and then continue there. However, the badge counter in discourse is not a count of unread notifications. If you click the badge the counter disappears, even if there are still unread notifications.

How can I determine the number in the light blue discourse notification badge counter and whether it is visible via the API?