2020-01-01 22:37:59 +01:00
---
2022-11-20 07:34:38 +01:00
title: notifications API methods
2020-01-01 22:37:59 +01:00
description: Receive notifications for activity on your account or statuses.
menu:
docs:
weight: 50
2022-11-20 07:34:38 +01:00
name: notifications
2020-01-01 22:37:59 +01:00
parent: methods
identifier: methods-notifications
2022-11-20 07:34:38 +01:00
aliases: [
"/methods/notifications",
"/api/methods/notifications",
]
2020-01-01 22:37:59 +01:00
---
2022-11-20 07:34:38 +01:00
< style >
#TableOfContents ul ul ul {display: none}
< / style >
## Get all notifications {#get}
```http
2022-12-14 22:55:30 +01:00
GET /api/v1/notifications HTTP/1.1
2022-11-20 07:34:38 +01:00
```
2020-01-01 22:37:59 +01:00
Notifications concerning the user. This API returns Link headers containing links to the next/previous page. However, the links can also be constructed dynamically using query params and `id` values.
2022-11-20 07:34:38 +01:00
Types to filter include:
- `mention` = Someone mentioned you in their status
- `status` = Someone you enabled notifications for has posted a status
- `reblog` = Someone boosted one of your statuses
- `follow` = Someone followed you
- `follow_request` = Someone requested to follow you
- `favourite` = Someone favourited one of your statuses
- `poll` = A poll you have voted in or created has ended
2022-12-14 22:55:30 +01:00
- `update` = A status you boosted with has been edited
2022-11-20 07:34:38 +01:00
- `admin.sign_up` = Someone signed up (optionally sent to admins)
- `admin.report` = A new report has been filed
**Returns:** Array of [Notification ]({{< relref "entities/Notification" >}} )\
2020-01-01 22:37:59 +01:00
**OAuth:** User token + `read:notifications` \
2020-07-01 02:11:40 +02:00
**Version history:**\
0.0.0 - added\
2022-11-20 07:34:38 +01:00
2.6.0 - added `min_id` \
2.9.0 - added `account_id` \
3.1.0 - added `follow_request` type\
3.3.0 - added `status` type; both `min_id` and `max_id` can be used at the same time now\
3.5.0 - added `types` ; add `update` and `admin.sign_up` types\
4.0.0 - added `admin.report` type
#### Request
##### Headers
Authorization
: {{< required > }} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
##### Query parameters
max_id
: String. Return results older than this ID
since_id
: String. Return results newer than this ID
min_id
: String. Return results immediately newer than this ID
limit
2022-12-14 22:55:30 +01:00
: Integer. Maximum number of results to return. Defaults to 15 notifications. Max 30 notifications.
2022-11-20 07:34:38 +01:00
types[]
: Array of String. Types to include in the result.
exclude_types[]
: Array of String. Types to exclude from the results.
account_id
: String. Return only notifications received from the specified account.
#### Response
Sample call with limit=2.
```http
GET https://mastodon.social/api/v1/notifications?limit=2 HTTP/1.1
Authorization: Bearer xxx
```
##### 200: OK
The response body contains one page of notifications. You can use the HTTP Link header for further pagination.
```http
2022-12-14 22:55:30 +01:00
Link: < https: / / mastodon . example / api / v1 / notifications ? max_id = 34975535 > ; rel="next", < https: / / mastodon . example / api / v1 / notifications ? min_id = 34975861 > ;
2022-11-20 07:34:38 +01:00
```
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
```json
2020-01-01 22:37:59 +01:00
[
{
"id": "34975861",
"type": "mention",
"created_at": "2019-11-23T07:49:02.064Z",
"account": {
"id": "971724",
"username": "zsc",
"acct": "zsc",
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
},
"status": {
"id": "103186126728896492",
"created_at": "2019-11-23T07:49:01.940Z",
"in_reply_to_id": "103186038209478945",
"in_reply_to_account_id": "14715",
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
"content": "< p >< span class = \"h-card \">< a href = \"https://mastodon.social/@trwnh \" class = \"u-url mention \"> @< span > trwnh</ span ></ a ></ span > sup!</ p > ",
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
"account": {
"id": "971724",
"username": "zsc",
"acct": "zsc",
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
},
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
"mentions": [
{
"id": "14715",
"username": "trwnh",
"url": "https://mastodon.social/@trwnh",
"acct": "trwnh"
}
],
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
}
},
{
"id": "34975535",
"type": "favourite",
"created_at": "2019-11-23T07:29:18.903Z",
"account": {
"id": "297420",
"username": "haskal",
"acct": "haskal@cybre.space",
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
},
"status": {
"id": "103186046267791694",
"created_at": "2019-11-23T07:28:34.210Z",
"in_reply_to_id": "103186044372624124",
"in_reply_to_account_id": "297420",
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
"account": {
"id": "14715",
"username": "trwnh",
"acct": "trwnh",
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
}
}
}
]
```
2022-11-20 07:34:38 +01:00
##### 401: Unauthorized
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
Invalid or missing Authorization header.
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
```json
2020-01-01 22:37:59 +01:00
{
"error": "The access token is invalid"
}
```
2022-11-20 07:34:38 +01:00
---
## Get a single notification {#get-one}
```http
2023-02-07 02:14:07 +01:00
GET /api/v1/notifications/:id HTTP/1.1
2022-11-20 07:34:38 +01:00
```
2020-01-01 22:37:59 +01:00
View information about a notification with a given ID.
2022-11-20 07:34:38 +01:00
**Returns:** [Notification ]({{< relref "entities/Notification" >}} )\
2020-01-01 22:37:59 +01:00
**OAuth:** User token + `read:notifications` \
2020-07-01 02:11:40 +02:00
**Version history:**\
0.0.0 - added
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
#### Request
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
##### Path parameters
:id
: {{< required > }} String. The ID of the Notification in the database.
##### Headers
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
Authorization
: {{< required > }} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
#### Response
##### 200: OK
A single Notification
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
```json
2020-01-01 22:37:59 +01:00
{
"id": "34975861",
"type": "mention",
"created_at": "2019-11-23T07:49:02.064Z",
"account": {
"id": "971724",
"username": "zsc",
"acct": "zsc",
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
},
"status": {
"id": "103186126728896492",
"created_at": "2019-11-23T07:49:01.940Z",
"in_reply_to_id": "103186038209478945",
"in_reply_to_account_id": "14715",
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
"content": "< p >< span class = \"h-card \">< a href = \"https://mastodon.social/@trwnh \" class = \"u-url mention \"> @< span > trwnh</ span ></ a ></ span > sup!</ p > ",
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
"account": {
"id": "971724",
"username": "zsc",
"acct": "zsc",
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
},
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
"mentions": [
{
"id": "14715",
"username": "trwnh",
"url": "https://mastodon.social/@trwnh",
"acct": "trwnh"
}
],
2022-11-20 07:34:38 +01:00
// ...
2020-01-01 22:37:59 +01:00
}
2022-11-20 07:34:38 +01:00
}
2020-01-01 22:37:59 +01:00
```
2022-11-20 07:34:38 +01:00
##### 401: Unauthorized
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
Invalid or missing Authorization header.
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
```json
2020-01-01 22:37:59 +01:00
{
"error": "The access token is invalid"
}
```
2022-11-20 07:34:38 +01:00
---
## Dismiss all notifications {#clear}
```http
2022-12-14 22:55:30 +01:00
POST /api/v1/notifications/clear HTTP/1.1
2022-11-20 07:34:38 +01:00
```
2020-01-01 22:37:59 +01:00
Clear all notifications from the server.
**Returns:** empty object\
**OAuth:** User token + `write:notifications` \
2020-07-01 02:11:40 +02:00
**Version history:**\
0.0.0 - added
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
#### Request
##### Headers
Authorization
: {{< required > }} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
#### Response
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
##### 200: OK
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
Notifications successfully cleared.
```json
2020-01-01 22:37:59 +01:00
{}
```
2022-11-20 07:34:38 +01:00
##### 401: Unauthorized
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
Invalid or missing Authorization header.
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
```json
2020-01-01 22:37:59 +01:00
{
"error": "The access token is invalid"
}
```
2022-11-20 07:34:38 +01:00
---
## Dismiss a single notification {#dismiss}
```http
2022-12-14 22:55:30 +01:00
POST /api/v1/notifications/:id/dismiss HTTP/1.1
2022-11-20 07:34:38 +01:00
```
Dismiss a single notification from the server.
2020-01-01 22:37:59 +01:00
**Returns:** empty object\
**OAuth:** User token + `write:notifications` \
2020-07-01 02:11:40 +02:00
**Version history:**\
1.3.0 - added
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
#### Request
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
##### Path parameters
:id
: {{< required > }} String. The ID of the Notification in the database.
##### Headers
Authorization
: {{< required > }} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
#### Response
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
##### 200: OK
Notification with given ID successfully dismissed
```json
2020-01-01 22:37:59 +01:00
{}
```
2022-11-20 07:34:38 +01:00
##### 401: Unauthorized
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
Invalid or missing Authorization header.
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
```json
2020-01-01 22:37:59 +01:00
{
"error": "The access token is invalid"
}
```
2022-11-20 07:34:38 +01:00
---
## (REMOVED) Dismiss a single notification {#dismiss-deprecated}
```http
2022-12-14 22:55:30 +01:00
POST /api/v1/notifications/dismiss HTTP/1.1
2022-11-20 07:34:38 +01:00
```
Dismiss a single notification from the server.
2020-01-01 22:37:59 +01:00
**Returns:** empty object\
**OAuth:** User token + `write:notifications` \
2020-07-01 02:11:40 +02:00
**Version history**:\
0.0.0 - available\
2022-11-20 07:34:38 +01:00
1.3.0 - deprecated in favor of [notifications/:id/dismiss ](#dismiss )
2020-07-01 02:11:40 +02:00
3.0.0 - removed
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
#### Request
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
##### Headers
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
Authorization
: {{< required > }} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
##### Form data parameters
id
: {{< required > }} String. The ID of the notification in the database.
#### Response
##### 200: OK
Notification with given ID successfully dismissed
```json
2020-01-01 22:37:59 +01:00
{}
```
2022-11-20 07:34:38 +01:00
##### 401: Unauthorized
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
Invalid or missing Authorization header.
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
```json
2020-01-01 22:37:59 +01:00
{
"error": "The access token is invalid"
}
```
2022-11-20 07:34:38 +01:00
---
## See also
{{< page-relref ref = "methods/push" caption = "push API methods" > }}
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
{{< caption-link url = "https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/notifications_controller.rb" caption = "app/controllers/api/v1/notifications_controller.rb" > }}