zelo72/documentation
1
0
Fork 0
mirror of https://github.com/mastodon/documentation synced 2025-04-11 22:56:17 +02:00
Code Issues 6 Releases Wiki Activity
documentation/content/en/methods/notifications.md
Claire b59b7fea62
Add documentation for /api/v2/notifications/policy (#1503) 
* Rename `NotificationPolicy` entity to `V1::NotificationPolicy`

* Add documentation for v2 NotificationPolicy

* Add deprecation warning
2024-08-22 11:20:40 +02:00

20 KiB
Raw Blame History

title description menu aliases
notifications API methods Receive notifications for activity on your account or statuses.
docs
weight name parent identifier
50 notifications methods methods-notifications
/methods/notifications
/api/methods/notifications

Get all notifications

GET /api/v1/notifications HTTP/1.1

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.

Types to filter include:

  • mention = Someone mentioned you in their status
  • status = Someone you enabled notifications for has posted a status
  • reblog = Someone boosted one of your statuses
  • follow = Someone followed you
  • follow_request = Someone requested to follow you
  • favourite = Someone favourited one of your statuses
  • poll = A poll you have voted in or created has ended
  • update = A status you boosted with has been edited
  • admin.sign_up = Someone signed up (optionally sent to admins)
  • admin.report = A new report has been filed

Returns: Array of [Notification]({{< relref "entities/Notification" >}})
OAuth: User token + read:notifications
Version history:
0.0.0 - added
2.6.0 - added min_id
2.9.0 - added account_id
3.1.0 - added follow_request type
3.3.0 - added status type; both min_id and max_id can be used at the same time now
3.5.0 - added types; add update and admin.sign_up types
4.0.0 - added admin.report type
4.1.0 - notification limit changed from 15 (max 30) to 40 (max 80)

Request

Headers
Authorization
{{}} 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 notifications. Max 80 notifications.
types[]
Array of String. Types to include in the result.
exclude_types[]
Array of String. Types to exclude from the results.
account_id
String. Return only notifications received from the specified account.

Response

Sample call with limit=2.

GET https://mastodon.social/api/v1/notifications?limit=2 HTTP/1.1
Authorization: Bearer xxx
200: OK

The response body contains one page of notifications. You can use the HTTP Link header for further pagination.

Link: <https://mastodon.example/api/v1/notifications?max_id=34975535>; rel="next", <https://mastodon.example/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",
        // ...
      }
    }
  }
]
401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}

Get a single notification

GET /api/v1/notifications/:id HTTP/1.1

View information about a notification with a given ID.

Returns: [Notification]({{< relref "entities/Notification" >}})
OAuth: User token + read:notifications
Version history:
0.0.0 - added

Request

Path parameters
:id
{{}} String. The ID of the Notification in the database.
Headers
Authorization
{{}} Provide this header with Bearer <user token> to gain authorized access to this API method.

Response

200: OK

A single Notification

{
  "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"
      }
    ],
    // ...
  }
}
401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}

Dismiss all notifications

POST /api/v1/notifications/clear HTTP/1.1

Clear all notifications from the server.

Returns: Empty
OAuth: User token + write:notifications
Version history:
0.0.0 - added

Request

Headers
Authorization
{{}} Provide this header with Bearer <user token> to gain authorized access to this API method.

Response

200: OK

Notifications successfully cleared.

{}
401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}

Dismiss a single notification

POST /api/v1/notifications/:id/dismiss HTTP/1.1

Dismiss a single notification from the server.

Returns: Empty
OAuth: User token + write:notifications
Version history:
1.3.0 - added

Request

Path parameters
:id
{{}} String. The ID of the Notification in the database.
Headers
Authorization
{{}} Provide this header with Bearer <user token> to gain authorized access to this API method.

Response

200: OK

Notification with given ID successfully dismissed

{}
401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}

(REMOVED) Dismiss a single notification

POST /api/v1/notifications/dismiss HTTP/1.1

Dismiss a single notification from the server.

Returns: Empty
OAuth: User token + write:notifications
Version history:
0.0.0 - available
1.3.0 - deprecated in favor of notifications/:id/dismiss 3.0.0 - removed

Request

Headers
Authorization
{{}} Provide this header with Bearer <user token> to gain authorized access to this API method.
Form data parameters
id
{{}} String. The ID of the notification in the database.

Response

200: OK

Notification with given ID successfully dismissed

{}
401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}

Get the number of unread notifications

GET /api/v1/notifications/unread_count HTTP/1.1

Get the (capped) number of unread notifications for the current user. A notification is considered unread if it is more recent than the [notifications read marker]({{< relref "methods/markers" >}}). Because the count is dependant on the parameters, it is computed every time and is thus a relatively slow operation (although faster than getting the full corresponding notifications), therefore the number of returned notifications is capped.

Returns: Hash with a single key of count
OAuth: User token + read:notifications
Version history:
4.3.0 - added

Request

Headers
Authorization
{{}} Provide this header with Bearer <user token> to gain authorized access to this API method.
Query parameters
limit
Integer. Maximum number of results to return. Defaults to 100 notifications. Max 1000 notifications.
types[]
Array of String. Types of notifications that should count towards unread notifications.
exclude_types[]
Array of String. Types of notifications that should not count towards unread notifications.
account_id
String. Only count unread notifications received from the specified account.

Response

200: OK

The response body contains the capped count of unread notifications.

{
  "count": 42,
}
401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}

Get the filtering policy for notifications

GET /api/v2/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 <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.

{
  "for_not_following": "accept",
  "for_not_followers": "accept",
  "for_new_accounts": "accept",
  "for_private_mentions": "drop",
  "for_limited_accounts": "filter",
  "summary": {
    "pending_requests_count": 0,
    "pending_notifications_count": 0
  }
}
401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}

Update the filtering policy for notifications

PATCH /api/v2/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 <user token> to gain authorized access to this API method.

Form data parameters

for_not_following
String. Whether to accept, filter or drop notifications from accounts the user is not following. drop will prevent creation of the notification object altogether (without preventing the underlying activity), filter will cause it to be marked as filtered, and accept will not affect its processing.
for_not_followers
String. Whether to accept, filter or drop notifications from accounts that are not following the user. drop will prevent creation of the notification object altogether (without preventing the underlying activity), filter will cause it to be marked as filtered, and accept will not affect its processing.
for_new_accounts
String. Whether to accept, filter or drop notifications from accounts created in the past 30 days. drop will prevent creation of the notification object altogether (without preventing the underlying activity), filter will cause it to be marked as filtered, and accept will not affect its processing.
for_private_mentions
String. Whether to accept, filter or drop notifications from private mentions. drop will prevent creation of the notification object altogether (without preventing the underlying activity), filter will cause it to be marked as filtered, and accept will not affect its processing. Replies to private mentions initiated by the user, as well as accounts the user follows, are always allowed, regardless of this value.
for_limited_accounts
String. Whether to accept, filter or drop notifications from accounts that were limited by a moderator. drop will prevent creation of the notification object altogether (without preventing the underlying activity), filter will cause it to be marked as filtered, and accept will not affect its processing.

Response

200: OK

The response body contains the updated notifications filtering policy for the user.

{
  "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.

{
  "error": "The access token is invalid"
}

Get all notification requests

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 <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.

Response

200: OK

The response body contains one page of notification requests. You can use the HTTP Link header for further pagination.

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"

[
  {
    "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.

{
  "error": "The access token is invalid"
}

Get a single notification request

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 <user token> to gain authorized access to this API method.

Response

200: OK

A single notification request.

  {
    "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.

{
  "error": "The access token is invalid"
}

Accept a single notification request

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 <user token> to gain authorized access to this API method.

Response

200: OK

A single notification request.

{}
401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}

Dismiss a single notification request

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 <user token> to gain authorized access to this API method.

Response

200: OK

A single notification request.

{}
401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}

See also

{{< page-relref ref="methods/push" caption="push API methods" >}}

{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/notifications_controller.rb" caption="app/controllers/api/v1/notifications_controller.rb" >}}