2022-11-20 07:34:38 +01:00
---
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",
]
---
< style >
#TableOfContents ul ul ul {display: none}
< / style >
## About the Web Push API {#about}
Mastodon natively supports the [Web Push API ](https://developer.mozilla.org/en-US/docs/Web/API/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 ](https://github.com/mozilla-services/autopush ), or more practically, see:
* [toot-relay ](https://github.com/DagAgren/toot-relay )
* [PushToFCM ](https://github.com/tateisu/PushToFCM )
* [metatext-apns ](https://github.com/metabolist/metatext-apns )
---
## Subscribe to push notifications {#create}
```http
2022-12-14 22:55:30 +01:00
POST /api/v1/push/subscription HTTP/1.1
2022-11-20 07:34:38 +01:00
```
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 ]({{< relref "entities/WebPushSubscription" >}} )\
**OAuth:** User token + `push` \
**Version history:**\
2.4.0 - added\
3.3.0 - added `data[alerts][status]` \
2023-02-07 02:14:07 +01:00
3.4.0 - added `data[policy]` \
2022-11-20 07:34:38 +01:00
3.5.0 - added `data[alerts][update]` and `data[alerts][admin.sign_up]` \
4.0.0 - added `data[alerts][admin.report]`
#### Request
##### Headers
Authorization
: {{< required > }} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
##### Form data parameters
subscription[endpoint]
: {{< required > }} String. The endpoint URL that is called when a notification event occurs.
subscription[keys][p256dh]
: {{< required > }} String. User agent public key. Base64 encoded string of a public key from a ECDH keypair using the `prime256v1` curve.
subscription[keys][auth]
: {{< required > }} String. Auth secret. Base64 encoded string of 16 bytes of random data.
2022-12-14 22:55:30 +01:00
data[alerts][mention]
: Boolean. Receive mention notifications? Defaults to false.
2022-11-20 07:34:38 +01:00
2022-12-14 22:55:30 +01:00
data[alerts][status]
: Boolean. Receive new subscribed account notifications? Defaults to false.
2022-11-20 07:34:38 +01:00
data[alerts][reblog]
: Boolean. Receive reblog notifications? Defaults to false.
2022-12-14 22:55:30 +01:00
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.
2022-11-20 07:34:38 +01:00
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.
2023-02-07 02:14:07 +01:00
data[policy]
2022-11-20 07:34:38 +01:00
: 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.
```json
{
"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.
```json
{
"error": "The access token is invalid"
}
```
---
## Get current subscription {#get}
```http
2022-12-14 22:55:30 +01:00
GET /api/v1/push/subscription HTTP/1.1
2022-11-20 07:34:38 +01:00
```
View the PushSubscription currently associated with this access token.
**Returns:** [WebPushSubscription ]({{< relref "entities/WebPushSubscription" >}} )\
**OAuth:** User token + `push` \
**Version history:**\
2.4.0 - added
#### Request
##### Headers
Authorization
: {{< required > }} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
#### Response
##### 200: OK
```json
{
"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.
```json
{
"error": "The access token is invalid"
}
```
##### 404: Not found
A PushSubscription does not exist for this token.
```json
{
"error": "Record not found"
}
```
---
## Change types of notifications {#update}
```http
2022-12-14 22:55:30 +01:00
PUT /api/v1/push/subscription HTTP/1.1
2022-11-20 07:34:38 +01:00
```
Updates the current push subscription. Only the data part can be updated. To change fundamentals, a new subscription must be created instead.
**Returns:** [WebPushSubscription ]({{< relref "entities/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]`
#### Request
##### Headers
Authorization
: {{< required > }} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
##### Form data parameters
2022-12-14 22:55:30 +01:00
data[alerts][mention]
: Boolean. Receive mention notifications? Defaults to false.
2022-11-20 07:34:38 +01:00
2022-12-14 22:55:30 +01:00
data[alerts][status]
: Boolean. Receive new subscribed account notifications? Defaults to false.
2022-11-20 07:34:38 +01:00
data[alerts][reblog]
: Boolean. Receive reblog notifications? Defaults to false.
2022-12-14 22:55:30 +01:00
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.
2022-11-20 07:34:38 +01:00
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.
policy
: String. Specify whether to receive push notifications from `all` , `followed` , `follower` , or `none` users.
#### Response
##### 200: OK
Updating a PushSubscription to only receive mention alerts
```json
{
"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="
}
```
##### 401: Unauthorized
Invalid or missing Authorization header.
```json
{
"error": "The access token is invalid"
}
```
##### 404: Not found
No existing PushSubscription for this token
```json
{
"error": "Record not found"
}
```
---
## Remove current subscription {#delete}
```http
2022-12-14 22:55:30 +01:00
DELETE /api/v1/push/subscription HTTP/1.1
2022-11-20 07:34:38 +01:00
```
Removes the current Web Push API subscription.
**Returns:** none\
**OAuth:** User token + `push` \
**Version history:**\
2.4.0 - added
#### Request
##### Headers
Authorization
: {{< required > }} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
#### Response
##### 200: OK
PushSubscription successfully deleted or did not exist previously
```json
{}
```
##### 401: Unauthorized
Invalid or missing Authorization header.
```json
{
"error": "The access token is invalid"
}
```
---
## See also
{{< caption-link url = "https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/push/subscriptions_controller.rb" caption = "app/controllers/api/v1/push/subscriptions_controller.rb" > }}