### Author:  [@Discourse](https://meta.discourse.org/u/Discourse)
#### Post date: [June 20, 2019, 11:42pm UTC](https://meta.discourse.org/t/get-notifications-via-the-api/120951/1 "2019-06-20T23:42:13Z")
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](https://meta.discourse.org/t/discourse-api-documentation/22706) 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=`.
### Optional query parameters
| Parameter | Description |
| --- | --- |
| `username` | The username to fetch notifications for |
| `filter` | Filter by read state: `read` or `unread` |
| `filter_by_types` | Comma-separated list of notification type names to filter by (e.g. `mentioned,replied`) |
| `offset` | Offset for pagination |
| `limit` | Number of notifications to return (max 60) |
### Example request
```plaintext
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
```json
{
"notifications": [
{
"id": 3,
"user_id": 5,
"external_id": null,
"notification_type": 12,
"read": true,
"high_priority": false,
"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,
"user_id": 5,
"external_id": null,
"notification_type": 6,
"read": true,
"high_priority": 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 interested in only showing unread notifications you can pass the `filter=unread` query parameter to have the server return only unread notifications. For example:
```plaintext
curl -X GET "http://localhost:8080/notifications.json?username=blake.erickson&filter=unread" \
-H "Api-Key: e81c4022f148c872a98fb38dac1d9619c7f5b245b42ba98fa467968bbed7551e" \
-H "Api-Username: system"
```
You can visit this page for a listing of [notification types](https://github.com/discourse/discourse/blob/main/app/models/notification.rb#L121-L170). 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
```plaintext
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:
```json
{
"success": "OK"
}
```
---
### Author:  [@Siyuan\_Dong](https://meta.discourse.org/u/Siyuan_Dong)
#### Post date: [November 8, 2019, 9:25am UTC](https://meta.discourse.org/t/get-notifications-via-the-api/120951/2 "2019-11-08T09:25:26Z")
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 ?
Regards,
siyuan
---
### Author:  [@hellekin](https://meta.discourse.org/u/hellekin)
#### Post date: [March 22, 2020, 2:46pm UTC](https://meta.discourse.org/t/get-notifications-via-the-api/120951/3 "2020-03-22T14:46:16Z")
Oh that will be useful to play with Discourse topics and Gitlab issues / commits / merge requests / etc.
---
### Author:  [@Nathanaa](https://meta.discourse.org/u/Nathanaa)
#### Post date: [January 12, 2022, 10:45pm UTC](https://meta.discourse.org/t/get-notifications-via-the-api/120951/4 "2022-01-12T22:45:12Z")
@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?
---
### Author:  [@Tarun\_Sharma](https://meta.discourse.org/u/Tarun_Sharma)
#### Post date: [September 22, 2025, 7:30am UTC](https://meta.discourse.org/t/get-notifications-via-the-api/120951/5 "2025-09-22T07:30:15Z")
1. I reacted on a post from account A I get notificaton data in notification api for that notification then when I reacted on same post with Account B I dont’t get it data in notification api.But when I remove my reaction from Account A then Account B notification data is coming in notification api.Then I again react on post with Account A notification data come in api then I remove notification from Account B then Account A notification data is coming.