diff --git a/content/en/entities/NotificationPolicy.md b/content/en/entities/NotificationPolicy.md new file mode 100644 index 0000000..a1049b2 --- /dev/null +++ b/content/en/entities/NotificationPolicy.md @@ -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" >}} + + + diff --git a/content/en/entities/NotificationRequest.md b/content/en/entities/NotificationRequest.md new file mode 100644 index 0000000..f2d70d0 --- /dev/null +++ b/content/en/entities/NotificationRequest.md @@ -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": "

@trwnh sup!

", + // ... + "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" >}} + + + diff --git a/content/en/methods/notifications.md b/content/en/methods/notifications.md index aeb6a7d..c36bdfe 100644 --- a/content/en/methods/notifications.md +++ b/content/en/methods/notifications.md @@ -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 +: {{}} Provide this header with `Bearer ` 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 +: {{}} Provide this header with `Bearer ` 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 +: {{}} Provide this header with `Bearer ` 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: ; rel="next", ; 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": "

@trwnh sup!

", + // ... + "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 +: {{}} String. The ID of the Notification in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` 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": "

@trwnh sup!

", + // ... + "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 +: {{}} String. The ID of the Notification in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` 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 +: {{}} String. The ID of the Notification in the database. + +##### Headers + +Authorization +: {{}} Provide this header with `Bearer ` 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" >}}