Add documentation for notification policies (#1447)
* Add documentation for GET /api/v1/notifications/policy * Add documentation for `PATCH /api/v1/notifications/policy` * Add documentation for `GET /api/v1/notifications/requests` * Add documentation for `GET /api/v1/notifications/requests/:id` * Add documentation for accepting and rejecting requests * Remove redundant HTTP request examples * Add documentation for the `NotificationPolicy` entity * Add documentation for the `NotificationRequest` entity
This commit is contained in:
Claire
GitHub
parent
61d28de915
commit
878e5836b7
|
|
@ -0,0 +1,87 @@
|
|||
---
|
||||
title: NotificationPolicy
|
||||
description: Represents the notification filtering policy of the user.
|
||||
menu:
|
||||
docs:
|
||||
parent: entities
|
||||
aliases: [
|
||||
"/entities/NotificationPolicy",
|
||||
]
|
||||
---
|
||||
|
||||
## Attributes
|
||||
|
||||
### `filter_not_following` {#filter_not_following}
|
||||
|
||||
**Description:** Whether to filter notifications from accounts the user is not following.\
|
||||
**Type:** Boolean\
|
||||
**Version history:**\
|
||||
4.3.0 - added
|
||||
|
||||
### `filter_not_followers` {#filter_not_followers}
|
||||
|
||||
**Description:** Whether to filter notifications from accounts that are not following the user.\
|
||||
**Type:** Boolean\
|
||||
**Version history:**\
|
||||
4.3.0 - added
|
||||
|
||||
### `filter_new_accounts` {#filter_new_accounts}
|
||||
|
||||
**Description:** Whether to filter notifications from accounts created in the past 30 days.\
|
||||
**Type:** Boolean\
|
||||
**Version history:**\
|
||||
4.3.0 - added
|
||||
|
||||
### `filter_private_mentions` {#filter_private_mentions}
|
||||
|
||||
**Description:** Whether to filter notifications from private mentions. Replies to private mentions initiated by the user, as well as accounts the user follows, are never filtered.\
|
||||
**Type:** Boolean\
|
||||
**Version history:**\
|
||||
4.3.0 - added
|
||||
|
||||
### `summary` {#summary}
|
||||
|
||||
**Description:** Summary of the filtered notifications
|
||||
**Type:** Hash\
|
||||
**Version history:**\
|
||||
4.3.0 - added
|
||||
|
||||
### `summary[pending_requests_count]` {#pending_requests_count}
|
||||
|
||||
**Description:** Number of different accounts from which the user has non-dismissed filtered notifications. Capped at 100.
|
||||
**Type:** Integer\
|
||||
**Version history:**\
|
||||
4.3.0 - added
|
||||
|
||||
### `summary[pending_notifications_count]` {#pending_notifications_count}
|
||||
|
||||
**Description:** Number of total non-dismissed filtered notifications. May be inaccurate.
|
||||
**Type:** Integer\
|
||||
**Version history:**\
|
||||
4.3.0 - added
|
||||
|
||||
## Example
|
||||
|
||||
```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
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
{{< page-relref ref="methods/notifications" caption="notifications API methods" >}}
|
||||
|
||||
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/notification_policy_serializer.rb" caption="app/serializers/rest/notification_policy_serializer.rb" >}}
|
||||
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,107 @@
|
|||
---
|
||||
title: NotificationRequest
|
||||
description: Represents a group of filtered notifications from a specific user.
|
||||
menu:
|
||||
docs:
|
||||
parent: entities
|
||||
aliases: [
|
||||
"/entities/NotificationRequest",
|
||||
]
|
||||
---
|
||||
|
||||
## Attributes
|
||||
|
||||
### `id` {#id}
|
||||
|
||||
**Description:** The id of the notification request in the database.\
|
||||
**Type:** String (cast from an integer, but not guaranteed to be a number)\
|
||||
**Version history:**\
|
||||
4.3.0 - added
|
||||
|
||||
### `created_at` {#created_at}
|
||||
|
||||
**Description:** The timestamp of the notification request, i.e. when the first filtered notification from that user was created.\
|
||||
**Type:** String (ISO 8601 Datetime)\
|
||||
**Version history:**\
|
||||
4.3.0 - added
|
||||
|
||||
### `updated_at` {#updated_at}
|
||||
|
||||
**Description:** The timestamp of when the notification request was last updated.\
|
||||
**Type:** String (ISO 8601 Datetime)\
|
||||
**Version history:**\
|
||||
4.3.0 - added
|
||||
|
||||
### `from_account` {#from_account}
|
||||
|
||||
**Description:** The account that performed the action that generated the filtered notifications.\
|
||||
**Type:** [Account]({{< relref "entities/Account" >}})\
|
||||
**Version history:**\
|
||||
4.3.0 - added
|
||||
|
||||
### `notifications_count` {#notifications_count}
|
||||
|
||||
**Description:** How many of this account's notifications were filtered.\
|
||||
**Type:** Integer\
|
||||
**Version history:**\
|
||||
4.3.0 - added
|
||||
|
||||
### `last_status` {{%optional%}} {#last_status}
|
||||
|
||||
**Description:** Most recent status associated with a filtered notification from that account.\
|
||||
**Type:** [Status]({{< relref "entities/Status" >}})\
|
||||
**Version history:**\
|
||||
4.3.0 - added
|
||||
|
||||
## Example
|
||||
|
||||
```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"
|
||||
}
|
||||
],
|
||||
// ...
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
{{< page-relref ref="methods/notifications" caption="notifications API methods" >}}
|
||||
|
||||
{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/notification_request_serializer.rb" caption="app/serializers/rest/notification_request_serializer.rb" >}}
|
||||
|
||||
|
||||
|
||||
|
|
@ -391,6 +391,395 @@ Invalid or missing Authorization header.
|
|||
|
||||
---
|
||||
|
||||
## Get the filtering policy for notifications {#get-policy}
|
||||
|
||||
```http
|
||||
GET /api/v1/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
|
||||
{
|
||||
"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"
|
||||
}
|
||||
```
|
||||
|
||||
## Update the filtering policy for notifications
|
||||
|
||||
```http
|
||||
PATCH /api/v1/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
|
||||
|
||||
filter_not_following
|
||||
: Boolean. Whether to filter notifications from accounts the user is not following.
|
||||
|
||||
filter_not_followers
|
||||
: Boolean. Whether to filter notifications from accounts that are not following the user.
|
||||
|
||||
filter_new_accounts
|
||||
: Boolean. Whether to filter notifications from accounts created in the past 30 days.
|
||||
|
||||
filter_private_mentions
|
||||
: Boolean. Whether to filter notifications from private mentions. Replies to private mentions initiated by the user, as well as accounts the user follows, are never filtered.
|
||||
|
||||
|
||||
#### 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.
|
||||
|
||||
dismissed
|
||||
: Boolean. Shows only dismissed requests if `true`, and only non-dismissed requests if `false`. Defaults to `false`.
|
||||
|
||||
#### 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}
|
||||
|
||||
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 single notification request.
|
||||
|
||||
```json
|
||||
{}
|
||||
```
|
||||
|
||||
##### 401: Unauthorized
|
||||
|
||||
Invalid or missing Authorization header.
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "The access token is invalid"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Accept 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 single notification request.
|
||||
|
||||
```json
|
||||
{}
|
||||
```
|
||||
|
||||
##### 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" >}}
|
||||
|
|
|
|||
Loading…
Reference in New Issue