From c1c822c509fa7570e8070050b9a848eabb92dbe8 Mon Sep 17 00:00:00 2001 From: Claire Date: Fri, 17 May 2024 16:07:24 +0200 Subject: [PATCH 1/8] Add documentation for GET /api/v1/notifications/policy --- content/en/methods/notifications.md | 56 +++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) diff --git a/content/en/methods/notifications.md b/content/en/methods/notifications.md index aeb6a7d91..8416e1ba8 100644 --- a/content/en/methods/notifications.md +++ b/content/en/methods/notifications.md @@ -391,6 +391,62 @@ 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 + +```http +GET https://mastodon.social/api/v1/notifications/policy HTTP/1.1 +Authorization: Bearer xxx +``` + +##### 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" +} +``` + +--- + ## See also {{< page-relref ref="methods/push" caption="push API methods" >}} From 1a31e692f20ce5c6d50b5eec72880f54044a6e70 Mon Sep 17 00:00:00 2001 From: Claire Date: Fri, 17 May 2024 16:33:54 +0200 Subject: [PATCH 2/8] Add documentation for `PATCH /api/v1/notifications/policy` --- content/en/methods/notifications.md | 64 +++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) diff --git a/content/en/methods/notifications.md b/content/en/methods/notifications.md index 8416e1ba8..080c24af5 100644 --- a/content/en/methods/notifications.md +++ b/content/en/methods/notifications.md @@ -445,6 +445,70 @@ Invalid or missing Authorization header. } ``` +## 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" +} +``` + --- ## See also From 26753073f33ce870881efcfd6d77aa46e40e71f6 Mon Sep 17 00:00:00 2001 From: Claire Date: Fri, 17 May 2024 16:50:49 +0200 Subject: [PATCH 3/8] Add documentation for `GET /api/v1/notifications/requests` --- content/en/methods/notifications.md | 108 ++++++++++++++++++++++++++++ 1 file changed, 108 insertions(+) diff --git a/content/en/methods/notifications.md b/content/en/methods/notifications.md index 080c24af5..7c589ef9f 100644 --- a/content/en/methods/notifications.md +++ b/content/en/methods/notifications.md @@ -511,6 +511,114 @@ Invalid or missing Authorization header. --- +## 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 + +Sample call with limit=2. + +```http +GET https://mastodon.social/api/v1/notifications/requests?limit=2 HTTP/1.1 +Authorization: Bearer xxx +``` + +##### 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" +} +``` + +--- + ## See also {{< page-relref ref="methods/push" caption="push API methods" >}} From 5826da97d56f7a199b2c5df0b47b2a7cf16e43dd Mon Sep 17 00:00:00 2001 From: Claire Date: Fri, 17 May 2024 17:41:21 +0200 Subject: [PATCH 4/8] Add documentation for `GET /api/v1/notifications/requests/:id` --- content/en/methods/notifications.md | 106 +++++++++++++++++++++++++--- 1 file changed, 96 insertions(+), 10 deletions(-) diff --git a/content/en/methods/notifications.md b/content/en/methods/notifications.md index 7c589ef9f..e8a447ad3 100644 --- a/content/en/methods/notifications.md +++ b/content/en/methods/notifications.md @@ -567,18 +567,18 @@ Link: }})\ +**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 + +```http +GET https://mastodon.social/api/v1/notifications/requests/112456967201894256 HTTP/1.1 +Authorization: Bearer xxx +``` + +##### 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" +} +``` + --- ## See also From aa52a2ca174b784f0cf0b5772a79acf07dd9848a Mon Sep 17 00:00:00 2001 From: Claire Date: Fri, 17 May 2024 17:54:44 +0200 Subject: [PATCH 5/8] Add documentation for accepting and rejecting requests --- content/en/methods/notifications.md | 106 ++++++++++++++++++++++++++++ 1 file changed, 106 insertions(+) diff --git a/content/en/methods/notifications.md b/content/en/methods/notifications.md index e8a447ad3..509cf7dbc 100644 --- a/content/en/methods/notifications.md +++ b/content/en/methods/notifications.md @@ -617,6 +617,8 @@ Invalid or missing Authorization header. } ``` +--- + ## Get a single notification request {#get-one-request} ```http @@ -705,6 +707,110 @@ Invalid or missing Authorization header. --- +## 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 +: {{}} 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 + +```http +POST https://mastodon.social/api/v1/notifications/requests/112456967201894256/accept HTTP/1.1 +Authorization: Bearer xxx +``` + +##### 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 + +```http +POST https://mastodon.social/api/v1/notifications/requests/112456967201894256/accept HTTP/1.1 +Authorization: Bearer xxx +``` + +##### 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" >}} From fc393b2e80344a8cccc35156d2550649ff00173e Mon Sep 17 00:00:00 2001 From: Claire Date: Wed, 22 May 2024 10:55:52 +0200 Subject: [PATCH 6/8] Remove redundant HTTP request examples --- content/en/methods/notifications.md | 31 ----------------------------- 1 file changed, 31 deletions(-) diff --git a/content/en/methods/notifications.md b/content/en/methods/notifications.md index 509cf7dbc..c36bdfe03 100644 --- a/content/en/methods/notifications.md +++ b/content/en/methods/notifications.md @@ -413,11 +413,6 @@ Authorization #### Response -```http -GET https://mastodon.social/api/v1/notifications/policy HTTP/1.1 -Authorization: Bearer xxx -``` - ##### 200: OK The response body contains the current notifications filtering policy for the user. @@ -550,13 +545,6 @@ dismissed #### Response -Sample call with limit=2. - -```http -GET https://mastodon.social/api/v1/notifications/requests?limit=2 HTTP/1.1 -Authorization: Bearer xxx -``` - ##### 200: OK The response body contains one page of notification requests. You can use the HTTP Link header for further pagination. @@ -646,11 +634,6 @@ Authorization #### Response -```http -GET https://mastodon.social/api/v1/notifications/requests/112456967201894256 HTTP/1.1 -Authorization: Bearer xxx -``` - ##### 200: OK A single notification request. @@ -709,10 +692,6 @@ Invalid or missing Authorization header. ## 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\ @@ -734,11 +713,6 @@ Authorization #### Response -```http -POST https://mastodon.social/api/v1/notifications/requests/112456967201894256/accept HTTP/1.1 -Authorization: Bearer xxx -``` - ##### 200: OK A single notification request. @@ -786,11 +760,6 @@ Authorization #### Response -```http -POST https://mastodon.social/api/v1/notifications/requests/112456967201894256/accept HTTP/1.1 -Authorization: Bearer xxx -``` - ##### 200: OK A single notification request. From 5151964beb9a55654f242a0cbb7d62d1274d1302 Mon Sep 17 00:00:00 2001 From: Claire Date: Wed, 22 May 2024 11:23:54 +0200 Subject: [PATCH 7/8] Add documentation for the `NotificationPolicy` entity --- content/en/entities/NotificationPolicy.md | 87 +++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 content/en/entities/NotificationPolicy.md diff --git a/content/en/entities/NotificationPolicy.md b/content/en/entities/NotificationPolicy.md new file mode 100644 index 000000000..a1049b249 --- /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" >}} + + + From 6151e755b26d4734ca3aa55a15595abbca726952 Mon Sep 17 00:00:00 2001 From: Claire Date: Wed, 22 May 2024 11:52:49 +0200 Subject: [PATCH 8/8] Add documentation for the `NotificationRequest` entity --- content/en/entities/NotificationRequest.md | 107 +++++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 content/en/entities/NotificationRequest.md diff --git a/content/en/entities/NotificationRequest.md b/content/en/entities/NotificationRequest.md new file mode 100644 index 000000000..f2d70d03d --- /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" >}} + + +