push

Subscribe to and receive push notifications when a server-side notification is received, via the Web Push API

Web Push API

Mastodon natively supports the Web Push API. You can utilize the same mechanisms for your native app. It requires running a proxy server that connects to Android’s and Apple’s proprietary notification gateways. However, the proxy server does not have access to the contents of the notifications. For a reference, see Mozilla’s web push server, or more practically, see:

• toot-relay

• PushToFCM

Subscribe to push notifications

POST https://mastodon.example/api/v1/push/subscription

Add a Web Push API subscription to receive notifications. Each access token can have one push subscription. If you create a new subscription, the old subscription is deleted. Returns: PushSubscription OAuth: User token + push Version history: 2.4.0 - added

Headers

Name	Type	Description
Authorization	string	Bearer <user token>

Request Body

Name	Type	Description
subscription[endpoint]	string	Endpoint URL that is called when a notification event occurs.
subscription[keys][p256dh]	string	User agent public key. Base64 encoded string of public key of ECDH key using prime256v1 curve.
subscription[keys][auth]	string	Auth secret. Base64 encoded string of 16 bytes of random data.
data[alerts][follow]	boolean	Receive follow notifications?
data[alerts][favourite]	boolean	Receive favourite notifications?
data[alerts][reblog]	boolean	Receive reblog notifications?
data[alerts][mention]	boolean	Receive mention notifications?
data[alerts][poll]	boolean	Receive poll notifications?

200 A new PushSubscription has been generated, which will send the requested alerts to your endpoint.

{
  "id": 328183,
  "endpoint": "https://yourdomain.example/listener",
  "alerts": {
    "follow": true,
    "favourite": true,
    "reblog": true,
    "mention": true,
    "poll": true
  },
  "server_key": "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M="
}

Get current subscription

GET https://mastodon.example/api/v1/push/subscription

View the PushSubscription currently associated with this access token. Returns: PushSubscription OAuth: User token + push Version history: 2.4.0 - added

Headers

Name	Type	Description
Authorization	string	Bearer <user token>

200

{
  "id": 328183,
  "endpoint": "https://yourdomain.example/listener",
  "alerts": {
    "follow": true,
    "favourite": true,
    "reblog": true,
    "mention": true,
    "poll": true
  },
  "server_key": "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M="
}

404 A PushSubscription does not exist for this token.

{
  "error": "Record not found"
}

Change types of notifications

PUT https://mastodon.example/api/v1/push/subscription

Updates the current push subscription. Only the data part can be updated. To change fundamentals, a new subscription must be created instead. Returns: PushSubscription OAuth: User token + push Version history: 2.4.0 - added

Headers

Name	Type	Description
Authorization	string	Bearer <user token>

Request Body

Name	Type	Description
data[alerts][follow]	boolean	Receive follow notifications?
data[alerts][favourite]	boolean	Receive favourite notifications?
data[alerts][reblog]	boolean	Receive reblog notifications?
data[alerts][mention]	boolean	Receive mention notifications?
data[alerts][poll]	boolean	Receive poll notifications?

200 Updating a PushSubscription to only receive mention alerts

{
  "id": 328183,
  "endpoint": "https://yourdomain.example/listener",
  "alerts": {
    "follow": false,
    "favourite": false,
    "reblog": false,
    "mention": true,
    "poll": false
  },
  "server_key": "BCk-QqERU0q-CfYZjcuB6lnyyOYfJ2AifKqfeGIm7Z-HiTU5T9eTG5GxVA0_OH5mMlI4UkkDTpaZwozy0TzdZ2M="
}

404 No existing PushSubscription for this token

{
  "error": "Record not found"
}

Remove current subscription

DELETE https://mastodon.example/api/v1/push/subscription

Removes the current Web Push API subscription. Returns: none OAuth: User token + push Version history: 2.4.0 - added

Headers

Name	Type	Description
Authorization	string	Bearer <user token>

200 PushSubscription successfully deleted or did not exist previously

{}