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:

post
Subscribe to push notifications

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

Request

Headers
Authorization
required
string
Bearer <user token>
Form Data Parameters
subscription[endpoint]
required
string
Endpoint URL that is called when a notification event occurs.
subscription[keys][p256dh]
required
string
User agent public key. Base64 encoded string of public key of ECDH key using prime256v1 curve.
subscription[keys][auth]
required
string
Auth secret. Base64 encoded string of 16 bytes of random data.
data[alerts][follow]
optional
boolean
Receive follow notifications?
data[alerts][favourite]
optional
boolean
Receive favourite notifications?
data[alerts][reblog]
optional
boolean
Receive reblog notifications?
data[alerts][mention]
optional
boolean
Receive mention notifications?
data[alerts][poll]
optional
boolean
Receive poll notifications?

Response

200: Success

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
Get current subscription

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

Request

Headers
Authorization
required
string
Bearer <user token>

Response

200: Success

{
  "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: Not Found

A PushSubscription does not exist for this token.

{
  "error": "Record not found"
}

put
Change types of notifications

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

Request

Headers
Authorization
required
string
Bearer <user token>
Form Data Parameters
data[alerts][follow]
optional
boolean
Receive follow notifications?
data[alerts][favourite]
optional
boolean
Receive favourite notifications?
data[alerts][reblog]
optional
boolean
Receive reblog notifications?
data[alerts][mention]
optional
boolean
Receive mention notifications?
data[alerts][poll]
optional
boolean
Receive poll notifications?

Response

200: Success

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: Not Found

No existing PushSubscription for this token

{
  "error": "Record not found"
}

delete
Remove current subscription

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

Request

Headers
Authorization
required
string
Bearer <user token>

Response

200: Success

PushSubscription successfully deleted or did not exist previously

{}

Last updated March 17, 2021 · Improve this page