mastodon/documentation: Full documentation repository for Mastodon @ 1017e91968b13e0c123dd92d2085f357153364e3

title: push API methods description: >- Subscribe to and receive push notifications when a server-side notification is received, via the Web Push API menu: docs:

weight: 10
name: push
parent: methods-notifications
identifier: methods-push

aliases: [ "/methods/push", "/api/methods/push", "/methods/notifications/push",

]

About the Web Push API {#about}

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:

Subscribe to push notifications {#create}

POST /api/v1/push/subscription HTTP/1.1

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: WebPushSubscription\ OAuth: User token + push\ Version history:\ 2.4.0 - added\ 3.3.0 - added data[alerts][status]\ 3.4.0 - added data[policy]\ 3.5.0 - added data[alerts][update] and data[alerts][admin.sign_up]\ 4.0.0 - added data[alerts][admin.report]

Request

Headers

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

Form data parameters

subscription[endpoint] : {{}} String. The endpoint URL that is called when a notification event occurs.

subscription[keys][p256dh] : {{}} String. User agent public key. Base64 encoded string of a public key from a ECDH keypair using the prime256v1 curve.

subscription[keys][auth] : {{}} String. Auth secret. Base64 encoded string of 16 bytes of random data.

data[alerts][mention] : Boolean. Receive mention notifications? Defaults to false.

data[alerts][status] : Boolean. Receive new subscribed account notifications? Defaults to false.

data[alerts][reblog] : Boolean. Receive reblog notifications? Defaults to false.

data[alerts][follow] : Boolean. Receive follow notifications? Defaults to false.

data[alerts][follow_request] : Boolean. Receive follow request notifications? Defaults to false.

data[alerts][favourite] : Boolean. Receive favourite notifications? Defaults to false.

data[alerts][poll] : Boolean. Receive poll notifications? Defaults to false.

data[alerts][update] : Boolean. Receive status edited notifications? Defaults to false.

data[alerts][admin.sign_up] : Boolean. Receive new user signup notifications? Defaults to false. Must have a role with the appropriate permissions.

data[alerts][admin.report] : Boolean. Receive new report notifications? Defaults to false. Must have a role with the appropriate permissions.

data[policy] : String. Specify whether to receive push notifications from all, followed, follower, or none users.

Response

200: OK

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="
}

401: Unauthorized

Invalid or missing Authorization header.

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

Get current subscription {#get}

GET /api/v1/push/subscription HTTP/1.1

View the PushSubscription currently associated with this access token.

Returns: WebPushSubscription\ OAuth: User token + push\ Version history:\ 2.4.0 - added

Request

Headers

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

Response

200: OK

{
  "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="
}

401: Unauthorized

Invalid or missing Authorization header.

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

404: Not found

A PushSubscription does not exist for this token.

{
  "error": "Record not found"
}

Change types of notifications {#update}

PUT /api/v1/push/subscription HTTP/1.1

Updates the current push subscription. Only the data part can be updated. To change fundamentals, a new subscription must be created instead.

Returns: WebPushSubscription\ OAuth: User token + push\ Version history:\ 2.4.0 - added\ 3.3.0 - added data[alerts][status]\ 3.4.0 - added policy\ 3.5.0 - added data[alerts][update] and data[alerts][admin.sign_up]\ 4.0.0 - added data[alerts][admin.report]