zelo72
/
documentation
mirror of https://github.com/mastodon/documentation
1
0
Fork 0
Code Issues 6 Releases Wiki Activity
documentation/content/en/methods/notifications.md

385 lines
11 KiB
Markdown
Raw Normal View History

Update documentation with contents by twrnh
2020-01-01 22:37:59 +01:00
---
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`\
update for 3.1 (#785)
2020-07-01 02:11:40 +02:00
**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
Update documentation with contents by twrnh
2020-01-01 22:37:59 +01:00
{{< endapi-method-description >}}
{{< api-method-spec >}}
{{< api-method-request >}}
{{< api-method-headers >}}
{{< api-method-parameter name="Authorization" type="string" required=true >}}
Bearer &lt;user token&gt;
{{< 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 >}}
update for 3.1 (#785)
2020-07-01 02:11:40 +02:00
Array of types to exclude \(`follow`, `favourite`, `reblog`, `mention`, `poll`, `follow_request`\)
Update documentation with contents by twrnh
2020-01-01 22:37:59 +01:00
{{< 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`\
update for 3.1 (#785)
2020-07-01 02:11:40 +02:00
**Version history:**\
0.0.0 - added
Update documentation with contents by twrnh
2020-01-01 22:37:59 +01:00
{{< 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 &lt;user token&gt;
{{< 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`\
update for 3.1 (#785)
2020-07-01 02:11:40 +02:00
**Version history:**\
0.0.0 - added
Update documentation with contents by twrnh
2020-01-01 22:37:59 +01:00
{{< endapi-method-description >}}
{{< api-method-spec >}}
{{< api-method-request >}}
{{< api-method-headers >}}
{{< api-method-parameter name="Authorization" type="string" required=true >}}
Bearer &lt;user token&gt;
{{< 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`\
update for 3.1 (#785)
2020-07-01 02:11:40 +02:00
**Version history:**\
1.3.0 - added
Update documentation with contents by twrnh
2020-01-01 22:37:59 +01:00
{{< 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 &lt;user token&gt;
{{< 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`\
update for 3.1 (#785)
2020-07-01 02:11:40 +02:00
**Version history**:\
0.0.0 - available\
3.0.0 - removed
Update documentation with contents by twrnh
2020-01-01 22:37:59 +01:00
{{< endapi-method-description >}}
{{< api-method-spec >}}
{{< api-method-request >}}
{{< api-method-headers >}}
{{< api-method-parameter name="Authorization" type="string" required=true >}}
Bearer &lt;user token&gt;
{{< 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 >}}