mirror of
https://github.com/mastodon/documentation
synced 2025-04-11 22:56:17 +02:00
cb3aa4de10
* Improve deprecation messaging for Application#vapid_key * Format JSON examples in Instance methods * Remove vapid_key from Apps API examples, since this property is deprecated on Application entity * Add documentation for new OAuth 2.0 features added in 4.3.0 * Improve documentation for oauth-scopes * Update content/en/api/oauth-scopes.md Co-authored-by: Matt Jankowski <matt@jankowski.online> * Update content/en/api/oauth-scopes.md Co-authored-by: Matt Jankowski <matt@jankowski.online> * Update content/en/api/oauth-scopes.md Co-authored-by: Matt Jankowski <matt@jankowski.online> * Update content/en/api/oauth-scopes.md Co-authored-by: Matt Jankowski <matt@jankowski.online> * Add deprecated and removed shortcode labels * Use deprecated and removed shortcodes * Improve OAuth documentation * More OAuth documentation improvements * Correct streaming API documentation after 4.2.0 changes * Add note about improved Push Subscription API validation in 4.3.0 * Fix inconsistent OAuth label formatting * Add note that there is a relationship between Accounts and the Application used to create them * Add note that application registration endpoint also supports JSON bodies * Be consistent in the formatting of placeholder values for Bearer tokens * code review changes * Slight changes in wording * Add documentation for PKCE * Removal of crypto oauth scope * Cross-link authorization's scope with the OAuth Scopes documentation * Update content/en/methods/oauth.md * Update content/en/api/oauth-scopes.md --------- Co-authored-by: Matt Jankowski <matt@jankowski.online> Co-authored-by: David Roetzel <david@roetzel.de>
996 lines
23 KiB
Markdown
996 lines
23 KiB
Markdown
---
|
|
title: notifications API methods
|
|
description: Receive notifications for activity on your account or statuses.
|
|
menu:
|
|
docs:
|
|
weight: 50
|
|
name: notifications
|
|
parent: methods
|
|
identifier: methods-notifications
|
|
aliases: [
|
|
"/methods/notifications",
|
|
"/api/methods/notifications",
|
|
]
|
|
---
|
|
|
|
<style>
|
|
#TableOfContents ul ul ul {display: none}
|
|
</style>
|
|
|
|
## Get all notifications {#get}
|
|
|
|
```http
|
|
GET /api/v1/notifications HTTP/1.1
|
|
```
|
|
|
|
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.
|
|
|
|
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
|
|
- `update` = A status you boosted with has been edited
|
|
- `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" >}})\
|
|
**OAuth:** User token + `read:notifications`\
|
|
**Version history:**\
|
|
0.0.0 - added\
|
|
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\
|
|
4.1.0 - notification limit changed from 15 (max 30) to 40 (max 80)\
|
|
4.3.0 - added `include_filtered` parameter
|
|
|
|
#### Request
|
|
|
|
##### Headers
|
|
|
|
Authorization
|
|
: {{<required>}} Provide this header with `Bearer <user_token>` to gain authorized access to this API method.
|
|
|
|
##### Query parameters
|
|
|
|
max_id
|
|
: String. All results returned will be lesser than this ID. In effect, sets an upper bound on results.
|
|
|
|
since_id
|
|
: String. All results returned will be greater than this ID. In effect, sets a lower bound on results.
|
|
|
|
min_id
|
|
: String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward.
|
|
|
|
limit
|
|
: Integer. Maximum number of results to return. Defaults to 40 notifications. Max 80 notifications.
|
|
|
|
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.
|
|
|
|
include_filtered
|
|
: Boolean. Whether to include notifications filtered by the user's [NotificationPolicy]({{< relref "entities/NotificationPolicy" >}}). Defaults to false.
|
|
|
|
#### Response
|
|
|
|
Sample call with limit=2.
|
|
|
|
```http
|
|
GET https://mastodon.social/api/v1/notifications?limit=2 HTTP/1.1
|
|
Authorization: Bearer <user_token>
|
|
```
|
|
|
|
##### 200: OK
|
|
|
|
The response body contains one page of notifications. You can use the HTTP Link header for further pagination.
|
|
|
|
```http
|
|
Link: <https://mastodon.example/api/v1/notifications?max_id=34975535>; rel="next", <https://mastodon.example/api/v1/notifications?min_id=34975861>;
|
|
```
|
|
|
|
```json
|
|
[
|
|
{
|
|
"id": "34975861",
|
|
"type": "mention",
|
|
"created_at": "2019-11-23T07:49:02.064Z",
|
|
"account": {
|
|
"id": "971724",
|
|
"username": "zsc",
|
|
"acct": "zsc",
|
|
// ...
|
|
},
|
|
"status": {
|
|
"id": "103186126728896492",
|
|
"created_at": "2019-11-23T07:49:01.940Z",
|
|
"in_reply_to_id": "103186038209478945",
|
|
"in_reply_to_account_id": "14715",
|
|
// ...
|
|
"content": "<p><span class=\"h-card\"><a href=\"https://mastodon.social/@trwnh\" class=\"u-url mention\">@<span>trwnh</span></a></span> sup!</p>",
|
|
// ...
|
|
"account": {
|
|
"id": "971724",
|
|
"username": "zsc",
|
|
"acct": "zsc",
|
|
// ...
|
|
},
|
|
// ...
|
|
"mentions": [
|
|
{
|
|
"id": "14715",
|
|
"username": "trwnh",
|
|
"url": "https://mastodon.social/@trwnh",
|
|
"acct": "trwnh"
|
|
}
|
|
],
|
|
// ...
|
|
}
|
|
},
|
|
{
|
|
"id": "34975535",
|
|
"type": "favourite",
|
|
"created_at": "2019-11-23T07:29:18.903Z",
|
|
"account": {
|
|
"id": "297420",
|
|
"username": "haskal",
|
|
"acct": "haskal@cybre.space",
|
|
// ...
|
|
},
|
|
"status": {
|
|
"id": "103186046267791694",
|
|
"created_at": "2019-11-23T07:28:34.210Z",
|
|
"in_reply_to_id": "103186044372624124",
|
|
"in_reply_to_account_id": "297420",
|
|
// ...
|
|
"account": {
|
|
"id": "14715",
|
|
"username": "trwnh",
|
|
"acct": "trwnh",
|
|
// ...
|
|
}
|
|
}
|
|
}
|
|
]
|
|
```
|
|
|
|
##### 401: Unauthorized
|
|
|
|
Invalid or missing Authorization header.
|
|
|
|
```json
|
|
{
|
|
"error": "The access token is invalid"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Get a single notification {#get-one}
|
|
|
|
```http
|
|
GET /api/v1/notifications/:id HTTP/1.1
|
|
```
|
|
|
|
View information about a notification with a given ID.
|
|
|
|
**Returns:** [Notification]({{< relref "entities/Notification" >}})\
|
|
**OAuth:** User token + `read:notifications`\
|
|
**Version history:**\
|
|
0.0.0 - added
|
|
|
|
#### Request
|
|
|
|
##### 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.
|
|
|
|
#### Response
|
|
|
|
##### 200: OK
|
|
|
|
A single Notification
|
|
|
|
```json
|
|
{
|
|
"id": "34975861",
|
|
"type": "mention",
|
|
"created_at": "2019-11-23T07:49:02.064Z",
|
|
"account": {
|
|
"id": "971724",
|
|
"username": "zsc",
|
|
"acct": "zsc",
|
|
// ...
|
|
},
|
|
"status": {
|
|
"id": "103186126728896492",
|
|
"created_at": "2019-11-23T07:49:01.940Z",
|
|
"in_reply_to_id": "103186038209478945",
|
|
"in_reply_to_account_id": "14715",
|
|
// ...
|
|
"content": "<p><span class=\"h-card\"><a href=\"https://mastodon.social/@trwnh\" class=\"u-url mention\">@<span>trwnh</span></a></span> sup!</p>",
|
|
// ...
|
|
"account": {
|
|
"id": "971724",
|
|
"username": "zsc",
|
|
"acct": "zsc",
|
|
// ...
|
|
},
|
|
// ...
|
|
"mentions": [
|
|
{
|
|
"id": "14715",
|
|
"username": "trwnh",
|
|
"url": "https://mastodon.social/@trwnh",
|
|
"acct": "trwnh"
|
|
}
|
|
],
|
|
// ...
|
|
}
|
|
}
|
|
```
|
|
|
|
##### 401: Unauthorized
|
|
|
|
Invalid or missing Authorization header.
|
|
|
|
```json
|
|
{
|
|
"error": "The access token is invalid"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Dismiss all notifications {#clear}
|
|
|
|
```http
|
|
POST /api/v1/notifications/clear HTTP/1.1
|
|
```
|
|
|
|
Clear all notifications from the server.
|
|
|
|
**Returns:** Empty\
|
|
**OAuth:** User token + `write:notifications`\
|
|
**Version history:**\
|
|
0.0.0 - added
|
|
|
|
#### Request
|
|
##### Headers
|
|
|
|
Authorization
|
|
: {{<required>}} Provide this header with `Bearer <user_token>` to gain authorized access to this API method.
|
|
|
|
#### Response
|
|
|
|
##### 200: OK
|
|
|
|
Notifications successfully cleared.
|
|
|
|
```json
|
|
{}
|
|
```
|
|
|
|
##### 401: Unauthorized
|
|
|
|
Invalid or missing Authorization header.
|
|
|
|
```json
|
|
{
|
|
"error": "The access token is invalid"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Dismiss a single notification {#dismiss}
|
|
|
|
```http
|
|
POST /api/v1/notifications/:id/dismiss HTTP/1.1
|
|
```
|
|
|
|
Dismiss a single notification from the server.
|
|
|
|
**Returns:** Empty\
|
|
**OAuth:** User token + `write:notifications`\
|
|
**Version history:**\
|
|
1.3.0 - added
|
|
|
|
#### Request
|
|
|
|
##### 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.
|
|
|
|
#### Response
|
|
|
|
##### 200: OK
|
|
|
|
Notification with given ID successfully dismissed
|
|
|
|
```json
|
|
{}
|
|
```
|
|
|
|
##### 401: Unauthorized
|
|
|
|
Invalid or missing Authorization header.
|
|
|
|
```json
|
|
{
|
|
"error": "The access token is invalid"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Dismiss a single notification {{%removed%}} {#dismiss-deprecated}
|
|
|
|
```http
|
|
POST /api/v1/notifications/dismiss HTTP/1.1
|
|
```
|
|
|
|
Dismiss a single notification from the server.
|
|
|
|
**Returns:** Empty\
|
|
**OAuth:** User token + `write:notifications`\
|
|
**Version history**:\
|
|
0.0.0 - available\
|
|
1.3.0 - deprecated in favor of [notifications/:id/dismiss](#dismiss)
|
|
3.0.0 - removed
|
|
|
|
#### Request
|
|
|
|
##### Headers
|
|
|
|
Authorization
|
|
: {{<required>}} Provide this header with `Bearer <user_token>` to gain authorized access to this API method.
|
|
|
|
##### Form data parameters
|
|
id
|
|
: {{<required>}} String. The ID of the notification in the database.
|
|
|
|
#### Response
|
|
|
|
##### 200: OK
|
|
|
|
Notification with given ID successfully dismissed
|
|
|
|
```json
|
|
{}
|
|
```
|
|
|
|
##### 401: Unauthorized
|
|
|
|
Invalid or missing Authorization header.
|
|
|
|
```json
|
|
{
|
|
"error": "The access token is invalid"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Get the number of unread notifications {#unread-count}
|
|
|
|
```http
|
|
GET /api/v1/notifications/unread_count HTTP/1.1
|
|
```
|
|
|
|
Get the (capped) number of unread notifications for the current user.
|
|
A notification is considered unread if it is more recent than the [notifications read marker]({{< relref "methods/markers" >}}).
|
|
Because the count is dependant on the parameters, it is computed every time and is thus a relatively slow operation (although faster than getting the full corresponding notifications), therefore the number of returned notifications is capped.
|
|
|
|
**Returns:** Hash with a single key of `count`\
|
|
**OAuth:** User token + `read:notifications`\
|
|
**Version history**:\
|
|
4.3.0 - added
|
|
|
|
#### Request
|
|
|
|
##### Headers
|
|
|
|
Authorization
|
|
: {{<required>}} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
|
|
|
|
##### Query parameters
|
|
|
|
limit
|
|
: Integer. Maximum number of results to return. Defaults to 100 notifications. Max 1000 notifications.
|
|
|
|
types[]
|
|
: Array of String. Types of notifications that should count towards unread notifications.
|
|
|
|
exclude_types[]
|
|
: Array of String. Types of notifications that should not count towards unread notifications.
|
|
|
|
account_id
|
|
: String. Only count unread notifications received from the specified account.
|
|
|
|
#### Response
|
|
|
|
##### 200: OK
|
|
|
|
The response body contains the capped count of unread notifications.
|
|
|
|
```json
|
|
{
|
|
"count": 42,
|
|
}
|
|
```
|
|
|
|
##### 401: Unauthorized
|
|
|
|
Invalid or missing Authorization header.
|
|
|
|
```json
|
|
{
|
|
"error": "The access token is invalid"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Get the filtering policy for notifications {#get-policy}
|
|
|
|
```http
|
|
GET /api/v2/notifications/policy HTTP/1.1
|
|
```
|
|
|
|
Notifications filtering policy for the user.
|
|
|
|
**Returns:** [NotificationPolicy]({{< relref "entities/NotificationPolicy" >}})\
|
|
**OAuth:** User token + `read:notifications`\
|
|
**Version history:**\
|
|
4.3.0 - added
|
|
|
|
#### Request
|
|
|
|
##### Headers
|
|
|
|
Authorization
|
|
: {{<required>}} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
|
|
|
|
#### Response
|
|
|
|
##### 200: OK
|
|
|
|
The response body contains the current notifications filtering policy for the user.
|
|
|
|
```json
|
|
{
|
|
"for_not_following": "accept",
|
|
"for_not_followers": "accept",
|
|
"for_new_accounts": "accept",
|
|
"for_private_mentions": "drop",
|
|
"for_limited_accounts": "filter",
|
|
"summary": {
|
|
"pending_requests_count": 0,
|
|
"pending_notifications_count": 0
|
|
}
|
|
}
|
|
```
|
|
|
|
##### 401: Unauthorized
|
|
|
|
Invalid or missing Authorization header.
|
|
|
|
```json
|
|
{
|
|
"error": "The access token is invalid"
|
|
}
|
|
```
|
|
|
|
## Update the filtering policy for notifications
|
|
|
|
```http
|
|
PATCH /api/v2/notifications/policy HTTP/1.1
|
|
```
|
|
|
|
Update the user's notifications filtering policy.
|
|
|
|
**Returns:** [NotificationPolicy]({{< relref "entities/NotificationPolicy" >}})\
|
|
**OAuth:** User token + `write:notifications`\
|
|
**Version history:**\
|
|
4.3.0 - added
|
|
|
|
#### Request
|
|
|
|
##### Headers
|
|
|
|
Authorization
|
|
: {{<required>}} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
|
|
|
|
#### Form data parameters
|
|
|
|
for_not_following
|
|
: String. Whether to `accept`, `filter` or `drop` notifications from accounts the user is not following. `drop` will prevent creation of the notification object altogether (without preventing the underlying activity), `filter` will cause it to be marked as filtered, and `accept` will not affect its processing.
|
|
|
|
for_not_followers
|
|
: String. Whether to `accept`, `filter` or `drop` notifications from accounts that are not following the user. `drop` will prevent creation of the notification object altogether (without preventing the underlying activity), `filter` will cause it to be marked as filtered, and `accept` will not affect its processing.
|
|
|
|
for_new_accounts
|
|
: String. Whether to `accept`, `filter` or `drop` notifications from accounts created in the past 30 days. `drop` will prevent creation of the notification object altogether (without preventing the underlying activity), `filter` will cause it to be marked as filtered, and `accept` will not affect its processing.
|
|
|
|
for_private_mentions
|
|
: String. Whether to `accept`, `filter` or `drop` notifications from private mentions. `drop` will prevent creation of the notification object altogether (without preventing the underlying activity), `filter` will cause it to be marked as filtered, and `accept` will not affect its processing. Replies to private mentions initiated by the user, as well as accounts the user follows, are always allowed, regardless of this value.
|
|
|
|
for_limited_accounts
|
|
: String. Whether to `accept`, `filter` or `drop` notifications from accounts that were limited by a moderator. `drop` will prevent creation of the notification object altogether (without preventing the underlying activity), `filter` will cause it to be marked as filtered, and `accept` will not affect its processing.
|
|
|
|
|
|
#### Response
|
|
|
|
##### 200: OK
|
|
|
|
The response body contains the updated notifications filtering policy for the user.
|
|
|
|
```json
|
|
{
|
|
"filter_not_following": false,
|
|
"filter_not_followers": false,
|
|
"filter_new_accounts": false,
|
|
"filter_private_mentions": true,
|
|
"summary": {
|
|
"pending_requests_count": 0,
|
|
"pending_notifications_count": 0
|
|
}
|
|
}
|
|
```
|
|
|
|
##### 401: Unauthorized
|
|
|
|
Invalid or missing Authorization header.
|
|
|
|
```json
|
|
{
|
|
"error": "The access token is invalid"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Get all notification requests {#get-requests}
|
|
|
|
```http
|
|
GET /api/v1/notifications/requests HTTP/1.1
|
|
```
|
|
|
|
Notification requests for notifications filtered by the user's policy. This API returns Link headers containing links to the next/previous page.
|
|
|
|
**Returns:** Array of [NotificationRequest]({{< relref "entities/NotificationRequest" >}})\
|
|
**OAuth:** User token + `read:notifications`\
|
|
**Version history:**\
|
|
4.3.0 - added
|
|
|
|
#### Request
|
|
|
|
##### Headers
|
|
|
|
Authorization
|
|
: {{<required>}} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
|
|
|
|
##### Query parameters
|
|
|
|
max_id
|
|
: String. All results returned will be lesser than this ID. In effect, sets an upper bound on results.
|
|
|
|
since_id
|
|
: String. All results returned will be greater than this ID. In effect, sets a lower bound on results.
|
|
|
|
min_id
|
|
: String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward.
|
|
|
|
limit
|
|
: Integer. Maximum number of results to return. Defaults to 40 notification requests. Max 80 notification requests.
|
|
|
|
#### Response
|
|
|
|
##### 200: OK
|
|
|
|
The response body contains one page of notification requests. You can use the HTTP Link header for further pagination.
|
|
|
|
```http
|
|
Link: <https://mastodon.example/api/v1/notifications/requests?max_id=112456967201894256>; rel="next", <https://mastodon.example/api/v1/notifications/requests?min_id=112456967201894256>; rel="prev"
|
|
```
|
|
|
|
```json
|
|
[
|
|
{
|
|
"id": "112456967201894256",
|
|
"created_at": "2024-05-17T14:45:41.171Z",
|
|
"updated_at": "2024-05-17T14:45:41.171Z",
|
|
"notifications_count": "1",
|
|
"account": {
|
|
"id": "971724",
|
|
"username": "zsc",
|
|
"acct": "zsc",
|
|
// ...
|
|
},
|
|
"last_status": {
|
|
"id": "103186126728896492",
|
|
"created_at": "2019-11-23T07:49:01.940Z",
|
|
"in_reply_to_id": "103186038209478945",
|
|
"in_reply_to_account_id": "14715",
|
|
// ...
|
|
"content": "<p><span class=\"h-card\"><a href=\"https://mastodon.social/@trwnh\" class=\"u-url mention\">@<span>trwnh</span></a></span> sup!</p>",
|
|
// ...
|
|
"account": {
|
|
"id": "971724",
|
|
"username": "zsc",
|
|
"acct": "zsc",
|
|
// ...
|
|
},
|
|
// ...
|
|
"mentions": [
|
|
{
|
|
"id": "14715",
|
|
"username": "trwnh",
|
|
"url": "https://mastodon.social/@trwnh",
|
|
"acct": "trwnh"
|
|
}
|
|
],
|
|
// ...
|
|
}
|
|
}
|
|
]
|
|
```
|
|
|
|
##### 401: Unauthorized
|
|
|
|
Invalid or missing Authorization header.
|
|
|
|
```json
|
|
{
|
|
"error": "The access token is invalid"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Get a single notification request {#get-one-request}
|
|
|
|
```http
|
|
GET /api/v1/notifications/requests/:id HTTP/1.1
|
|
```
|
|
|
|
View information about a notification request with a given ID.
|
|
|
|
**Returns:** [NotificationRequest]({{< relref "entities/NotificationRequest" >}})\
|
|
**OAuth:** User token + `read:notifications`\
|
|
**Version history:**\
|
|
4.3.0 - added
|
|
|
|
#### Request
|
|
|
|
##### 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.
|
|
|
|
#### Response
|
|
|
|
##### 200: OK
|
|
|
|
A single notification request.
|
|
|
|
```json
|
|
{
|
|
"id": "112456967201894256",
|
|
"created_at": "2024-05-17T14:45:41.171Z",
|
|
"updated_at": "2024-05-17T14:45:41.171Z",
|
|
"notifications_count": "1",
|
|
"account": {
|
|
"id": "971724",
|
|
"username": "zsc",
|
|
"acct": "zsc",
|
|
// ...
|
|
},
|
|
"last_status": {
|
|
"id": "103186126728896492",
|
|
"created_at": "2019-11-23T07:49:01.940Z",
|
|
"in_reply_to_id": "103186038209478945",
|
|
"in_reply_to_account_id": "14715",
|
|
// ...
|
|
"content": "<p><span class=\"h-card\"><a href=\"https://mastodon.social/@trwnh\" class=\"u-url mention\">@<span>trwnh</span></a></span> sup!</p>",
|
|
// ...
|
|
"account": {
|
|
"id": "971724",
|
|
"username": "zsc",
|
|
"acct": "zsc",
|
|
// ...
|
|
},
|
|
// ...
|
|
"mentions": [
|
|
{
|
|
"id": "14715",
|
|
"username": "trwnh",
|
|
"url": "https://mastodon.social/@trwnh",
|
|
"acct": "trwnh"
|
|
}
|
|
],
|
|
// ...
|
|
}
|
|
}
|
|
```
|
|
|
|
##### 401: Unauthorized
|
|
|
|
Invalid or missing Authorization header.
|
|
|
|
```json
|
|
{
|
|
"error": "The access token is invalid"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Accept a single notification request {#accept-request}
|
|
|
|
```http
|
|
POST /api/v1/notifications/requests/:id/accept HTTP/1.1
|
|
```
|
|
|
|
Accept a notification request, which merges the filtered notifications from that user back into the main notification and accepts any future notification from them.
|
|
|
|
**Returns:** Empty\
|
|
**OAuth:** User token + `write:notifications`\
|
|
**Version history:**\
|
|
4.3.0 - added
|
|
|
|
#### Request
|
|
|
|
##### 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.
|
|
|
|
#### Response
|
|
|
|
##### 200: OK
|
|
|
|
A successful call will return an empty object.
|
|
|
|
```json
|
|
{}
|
|
```
|
|
|
|
##### 401: Unauthorized
|
|
|
|
Invalid or missing Authorization header.
|
|
|
|
```json
|
|
{
|
|
"error": "The access token is invalid"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Dismiss a single notification request {#dismiss-request}
|
|
|
|
```http
|
|
POST /api/v1/notifications/requests/:id/dismiss HTTP/1.1
|
|
```
|
|
|
|
Dismiss a notification request, which hides it and prevent it from contributing to the pending notification requests count.
|
|
|
|
**Returns:** Empty\
|
|
**OAuth:** User token + `write:notifications`\
|
|
**Version history:**\
|
|
4.3.0 - added
|
|
|
|
#### Request
|
|
|
|
##### 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.
|
|
|
|
#### Response
|
|
|
|
##### 200: OK
|
|
|
|
A successful call will return an empty object.
|
|
|
|
```json
|
|
{}
|
|
```
|
|
|
|
##### 401: Unauthorized
|
|
|
|
Invalid or missing Authorization header.
|
|
|
|
```json
|
|
{
|
|
"error": "The access token is invalid"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Accept multiple notification requests {#accept-multiple-requests}
|
|
|
|
```http
|
|
POST /api/v1/notifications/requests/accept HTTP/1.1
|
|
```
|
|
|
|
Accepts multiple notification requests, which merges the filtered notifications from those users back into the main notifications and accepts any future notification from them.
|
|
|
|
**Returns:** Empty\
|
|
**OAuth:** User token + `write:notifications`\
|
|
**Version history:**\
|
|
4.3.0 - added
|
|
|
|
#### Request
|
|
|
|
##### Form data parameters
|
|
|
|
:id[]
|
|
: {{<required>}} Array of String. The IDs of the notification requests in the database.
|
|
|
|
##### Headers
|
|
|
|
Authorization
|
|
: {{<required>}} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
|
|
|
|
#### Response
|
|
|
|
##### 200: OK
|
|
|
|
A successful call will return an empty object.
|
|
|
|
```json
|
|
{}
|
|
```
|
|
|
|
##### 401: Unauthorized
|
|
|
|
Invalid or missing Authorization header.
|
|
|
|
```json
|
|
{
|
|
"error": "The access token is invalid"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Dismiss multiple notification requests {#dismiss-multiple-requests}
|
|
|
|
```http
|
|
POST /api/v1/notifications/requests/dismiss HTTP/1.1
|
|
```
|
|
|
|
Dismiss multiple notification requests, which hides them and prevent them from contributing to the pending notification requests count.
|
|
|
|
**Returns:** Empty\
|
|
**OAuth:** User token + `write:notifications`\
|
|
**Version history:**\
|
|
4.3.0 - added
|
|
|
|
#### Request
|
|
|
|
##### Form data parameters
|
|
|
|
:id[]
|
|
: {{<required>}} Array of String. The IDs of the notification requests in the database.
|
|
|
|
##### Headers
|
|
|
|
Authorization
|
|
: {{<required>}} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
|
|
|
|
#### Response
|
|
|
|
##### 200: OK
|
|
|
|
A successful call will return an empty object.
|
|
|
|
```json
|
|
{}
|
|
```
|
|
|
|
##### 401: Unauthorized
|
|
|
|
Invalid or missing Authorization header.
|
|
|
|
```json
|
|
{
|
|
"error": "The access token is invalid"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Check if accepted notification requests have been merged {#requests-merged}
|
|
|
|
```http
|
|
GET /api/v1/notifications/requests/merged
|
|
```
|
|
|
|
Check whether accepted notification requests have been merged.
|
|
Accepting notification requests schedules a background job to merge the filtered notifications back into the normal notification list. When that process has finished, the client should refresh the notifications list at its earliest convenience. This is communicated by the `notifications_merged` streaming event but can also be polled using this endpoint.
|
|
|
|
***Returns:** Hash with a single boolean attribute `merged`\
|
|
**OAuth:** User token + `read:notifications`\
|
|
**Version history:**\
|
|
4.3.0 - added
|
|
|
|
#### Request
|
|
|
|
##### Headers
|
|
|
|
Authorization
|
|
: {{<required>}} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
|
|
|
|
#### Response
|
|
|
|
##### 200: OK
|
|
|
|
A successful call returns whether the notifications have been merged and are ready for being loaded.
|
|
|
|
```json
|
|
{
|
|
"merged": false
|
|
}
|
|
```
|
|
|
|
##### 401: Unauthorized
|
|
|
|
Invalid or missing Authorization header.
|
|
|
|
```json
|
|
{
|
|
"error": "The access token is invalid"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## See also
|
|
|
|
{{< page-relref ref="methods/push" caption="push API methods" >}}
|
|
|
|
{{< 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" >}}
|