385 lines
11 KiB
Markdown
385 lines
11 KiB
Markdown
---
|
|
title: notifications
|
|
description: Receive notifications for activity on your account or statuses.
|
|
menu:
|
|
docs:
|
|
weight: 50
|
|
parent: methods
|
|
identifier: methods-notifications
|
|
---
|
|
|
|
{{< api-method method="get" host="https://mastodon.example" path="/api/v1/notifications" title="Get all notifications" >}}
|
|
{{< api-method-description >}}
|
|
|
|
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.
|
|
|
|
**Returns:** Array of Notification\
|
|
**OAuth:** User token + `read:notifications`\
|
|
**Version history:**\
|
|
0.0.0 - added\
|
|
2.6.0 - add `min_id`\
|
|
2.9.0 - add `account_id`\
|
|
3.1.0 - add `follow_request` type
|
|
|
|
{{< endapi-method-description >}}
|
|
{{< api-method-spec >}}
|
|
{{< api-method-request >}}
|
|
{{< api-method-headers >}}
|
|
{{< api-method-parameter name="Authorization" type="string" required=true >}}
|
|
Bearer <user token>
|
|
{{< endapi-method-parameter >}}
|
|
{{< endapi-method-headers >}}
|
|
{{< api-method-query-parameters >}}
|
|
{{< api-method-parameter name="max_id" type="string" required=false >}}
|
|
Return results older than this ID
|
|
{{< endapi-method-parameter >}}
|
|
{{< api-method-parameter name="since_id" type="string" required=false >}}
|
|
Return results newer than this ID
|
|
{{< endapi-method-parameter >}}
|
|
{{< api-method-parameter name="min_id" type="string" required=false >}}
|
|
Return results immediately newer than this ID
|
|
{{< endapi-method-parameter >}}
|
|
{{< api-method-parameter name="limit" type="string" required=false >}}
|
|
Maximum number of results to return \(default 20\)
|
|
{{< endapi-method-parameter >}}
|
|
{{< api-method-parameter name="exclude_types" type="array" required=false >}}
|
|
Array of types to exclude \(`follow`, `favourite`, `reblog`, `mention`, `poll`, `follow_request`\)
|
|
{{< endapi-method-parameter >}}
|
|
{{< api-method-parameter name="account_id" type="string" required=false >}}
|
|
Return only notifications received from this account
|
|
{{< endapi-method-parameter >}}
|
|
{{< endapi-method-query-parameters >}}
|
|
{{< endapi-method-request >}}
|
|
{{< api-method-response >}}
|
|
{{< api-method-response-example httpCode=200 >}}
|
|
{{< api-method-response-example-description >}}
|
|
|
|
Sample call with limit=2. Use the Link header for pagination
|
|
{{< endapi-method-response-example-description >}}
|
|
|
|
|
|
```javascript
|
|
Link: <https://mastodon.social/api/v1/notifications?max_id=34975535>; rel="next", <https://mastodon.social/api/v1/notifications?min_id=34975861>;
|
|
|
|
[
|
|
{
|
|
"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",
|
|
...
|
|
}
|
|
}
|
|
}
|
|
]
|
|
```
|
|
{{< endapi-method-response-example >}}
|
|
{{< api-method-response-example httpCode=401 >}}
|
|
{{< api-method-response-example-description >}}
|
|
|
|
Invalid or missing Authorization header
|
|
{{< endapi-method-response-example-description >}}
|
|
|
|
|
|
```javascript
|
|
{
|
|
"error": "The access token is invalid"
|
|
}
|
|
```
|
|
{{< endapi-method-response-example >}}
|
|
{{< endapi-method-response >}}
|
|
{{< endapi-method-spec >}}
|
|
{{< endapi-method >}}
|
|
{{< api-method method="get" host="https://mastodon.example" path="/api/v1/notifications/:id" title="Get a single notification" >}}
|
|
{{< api-method-description >}}
|
|
|
|
View information about a notification with a given ID.
|
|
|
|
**Returns:** Notification\
|
|
**OAuth:** User token + `read:notifications`\
|
|
**Version history:**\
|
|
0.0.0 - added
|
|
|
|
{{< endapi-method-description >}}
|
|
{{< api-method-spec >}}
|
|
{{< api-method-request >}}
|
|
{{< api-method-path-parameters >}}
|
|
{{< api-method-parameter name=":id" type="string" required=true >}}
|
|
ID of the notification in the database.
|
|
{{< endapi-method-parameter >}}
|
|
{{< endapi-method-path-parameters >}}
|
|
{{< api-method-headers >}}
|
|
{{< api-method-parameter name="Authorization" type="string" required=true >}}
|
|
Bearer <user token>
|
|
{{< endapi-method-parameter >}}
|
|
{{< endapi-method-headers >}}
|
|
{{< endapi-method-request >}}
|
|
{{< api-method-response >}}
|
|
{{< api-method-response-example httpCode=200 >}}
|
|
{{< api-method-response-example-description >}}
|
|
|
|
A single Notification
|
|
{{< endapi-method-response-example-description >}}
|
|
|
|
|
|
```javascript
|
|
{
|
|
"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"
|
|
}
|
|
],
|
|
...
|
|
}
|
|
},
|
|
```
|
|
{{< endapi-method-response-example >}}
|
|
{{< api-method-response-example httpCode=401 >}}
|
|
{{< api-method-response-example-description >}}
|
|
|
|
Invalid or missing Authorization header
|
|
{{< endapi-method-response-example-description >}}
|
|
|
|
|
|
```javascript
|
|
{
|
|
"error": "The access token is invalid"
|
|
}
|
|
```
|
|
{{< endapi-method-response-example >}}
|
|
{{< endapi-method-response >}}
|
|
{{< endapi-method-spec >}}
|
|
{{< endapi-method >}}
|
|
{{< api-method method="post" host="https://mastodon.example" path="/api/v1/notifications/clear" title="Dismiss all notifications" >}}
|
|
{{< api-method-description >}}
|
|
|
|
Clear all notifications from the server.
|
|
|
|
**Returns:** empty object\
|
|
**OAuth:** User token + `write:notifications`\
|
|
**Version history:**\
|
|
0.0.0 - added
|
|
|
|
{{< endapi-method-description >}}
|
|
{{< api-method-spec >}}
|
|
{{< api-method-request >}}
|
|
{{< api-method-headers >}}
|
|
{{< api-method-parameter name="Authorization" type="string" required=true >}}
|
|
Bearer <user token>
|
|
{{< endapi-method-parameter >}}
|
|
{{< endapi-method-headers >}}
|
|
{{< endapi-method-request >}}
|
|
{{< api-method-response >}}
|
|
{{< api-method-response-example httpCode=200 >}}
|
|
{{< api-method-response-example-description >}}
|
|
|
|
Notifications successfully cleared
|
|
{{< endapi-method-response-example-description >}}
|
|
|
|
|
|
```javascript
|
|
{}
|
|
```
|
|
{{< endapi-method-response-example >}}
|
|
{{< api-method-response-example httpCode=401 >}}
|
|
{{< api-method-response-example-description >}}
|
|
|
|
Invalid or missing Authorization header
|
|
{{< endapi-method-response-example-description >}}
|
|
|
|
|
|
```javascript
|
|
{
|
|
"error": "The access token is invalid"
|
|
}
|
|
```
|
|
{{< endapi-method-response-example >}}
|
|
{{< endapi-method-response >}}
|
|
{{< endapi-method-spec >}}
|
|
{{< endapi-method >}}
|
|
{{< api-method method="post" host="https://mastodon.example" path="/api/v1/notifications/:id/dismiss" title="Dismiss a single notification" >}}
|
|
{{< api-method-description >}}
|
|
|
|
Clear a single notification from the server.
|
|
|
|
**Returns:** empty object\
|
|
**OAuth:** User token + `write:notifications`\
|
|
**Version history:**\
|
|
1.3.0 - added
|
|
|
|
{{< endapi-method-description >}}
|
|
{{< api-method-spec >}}
|
|
{{< api-method-request >}}
|
|
{{< api-method-path-parameters >}}
|
|
{{< api-method-parameter name=":id" type="string" required=true >}}
|
|
ID of the notification to be cleared
|
|
{{< endapi-method-parameter >}}
|
|
{{< endapi-method-path-parameters >}}
|
|
{{< api-method-headers >}}
|
|
{{< api-method-parameter name="Authorization" type="string" required=true >}}
|
|
Bearer <user token>
|
|
{{< endapi-method-parameter >}}
|
|
{{< endapi-method-headers >}}
|
|
{{< endapi-method-request >}}
|
|
{{< api-method-response >}}
|
|
{{< api-method-response-example httpCode=200 >}}
|
|
{{< api-method-response-example-description >}}
|
|
|
|
Notification with given ID successfully dismissed
|
|
{{< endapi-method-response-example-description >}}
|
|
|
|
|
|
```javascript
|
|
{}
|
|
```
|
|
{{< endapi-method-response-example >}}
|
|
{{< api-method-response-example httpCode=401 >}}
|
|
{{< api-method-response-example-description >}}
|
|
|
|
Invalid or missing Authorization header
|
|
{{< endapi-method-response-example-description >}}
|
|
|
|
|
|
```javascript
|
|
{
|
|
"error": "The access token is invalid"
|
|
}
|
|
```
|
|
{{< endapi-method-response-example >}}
|
|
{{< endapi-method-response >}}
|
|
{{< endapi-method-spec >}}
|
|
{{< endapi-method >}}
|
|
{{< api-method method="post" host="https://mastodon.example" path="/api/v1/notifications/dismiss" title="\(DEPRECATED\) Dismiss a single notification" >}}
|
|
{{< api-method-description >}}
|
|
|
|
Delete a single notification from the server.
|
|
|
|
**Returns:** empty object\
|
|
**OAuth:** User token + `write:notifications`\
|
|
**Version history**:\
|
|
0.0.0 - available\
|
|
3.0.0 - removed
|
|
|
|
{{< endapi-method-description >}}
|
|
{{< api-method-spec >}}
|
|
{{< api-method-request >}}
|
|
{{< api-method-headers >}}
|
|
{{< api-method-parameter name="Authorization" type="string" required=true >}}
|
|
Bearer <user token>
|
|
{{< endapi-method-parameter >}}
|
|
{{< endapi-method-headers >}}
|
|
{{< api-method-form-data-parameters >}}
|
|
{{< api-method-parameter name="id" type="string" required=true >}}
|
|
ID of the notification to be cleared, passed as a parameter
|
|
{{< endapi-method-parameter >}}
|
|
{{< endapi-method-form-data-parameters >}}
|
|
{{< endapi-method-request >}}
|
|
{{< api-method-response >}}
|
|
{{< api-method-response-example httpCode=200 >}}
|
|
{{< api-method-response-example-description >}}
|
|
|
|
Notification with given ID successfully dismissed
|
|
{{< endapi-method-response-example-description >}}
|
|
|
|
|
|
```javascript
|
|
{}
|
|
```
|
|
{{< endapi-method-response-example >}}
|
|
{{< api-method-response-example httpCode=401 >}}
|
|
{{< api-method-response-example-description >}}
|
|
|
|
Invalid or missing Authorization header
|
|
{{< endapi-method-response-example-description >}}
|
|
|
|
|
|
```javascript
|
|
{
|
|
"error": "The access token is invalid"
|
|
}
|
|
```
|
|
{{< endapi-method-response-example >}}
|
|
{{< endapi-method-response >}}
|
|
{{< endapi-method-spec >}}
|
|
{{< endapi-method >}}
|
|
|
|
|