notifications

Receive notifications for activity on your account or statuses.

Get all notifications

GET https://mastodon.example/api/v1/notifications

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 Version history: 0.0.0 - added 2.6.0 - add min_id 2.9.0 - add account_id

Query Parameters

Name	Type	Description
max_id	string	Return results older than this ID
since_id	string	Return results newer than this ID
min_id	string	Return results immediately newer than this ID
limit	string	Maximum number of results to return (default 20)
exclude_types	array	Array of types to exclude (follow, favourite, reblog, mention, poll)
account_id	string	Return only notifications received from this account

Headers

Name	Type	Description
Authorization	string	Bearer <user token>

200 Sample call with limit=2. Use the Link header for pagination

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": "[e-mail]",
      ...
    },
    "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 Invalid or missing Authorization header

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

Get a single notification

GET https://mastodon.example/api/v1/notifications/:id

View information about a notification with a given ID. Returns: Notification OAuth: User token + read:notifications Version history: 0.0.0 - added

Path Parameters

Name	Type	Description
:id	string	ID of the notification in the database.

Headers

Name	Type	Description
Authorization	string	Bearer <user token>

200 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 Invalid or missing Authorization header

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

Dismiss all notifications

POST https://mastodon.example/api/v1/notifications/clear

Clear all notifications from the server. Returns: empty object OAuth: User token + write:notifications Version history: 0.0.0 - added

Headers

Name	Type	Description
Authorization	string	Bearer <user token>

200 Notifications successfully cleared

{}

401 Invalid or missing Authorization header

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

Dismiss a single notification

POST https://mastodon.example/api/v1/notifications/:id/dismiss

Clear a single notification from the server. Returns: empty object OAuth: User token + write:notifications Version history: 1.3.0 - added

Path Parameters

Name	Type	Description
:id	string	ID of the notification to be cleared

Headers

Name	Type	Description
Authorization	string	Bearer <user token>

200 Notification with given ID successfully dismissed

{}

401 Invalid or missing Authorization header

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

(DEPRECATED) Dismiss a single notification

POST https://mastodon.example/api/v1/notifications/dismiss

Delete a single notification from the server. Returns: empty object OAuth: User token + write:notifications Version history: 0.0.0 - available 3.0.0 - removed

Headers

Name	Type	Description
Authorization	string	Bearer <user token>

Request Body

Name	Type	Description
id	string	ID of the notification to be cleared, passed as a parameter

200 Notification with given ID successfully dismissed

{}

401 Invalid or missing Authorization header

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