# push

## Web Push API

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)

## Subscribe to push notifications

<mark style="color:green;">`POST`</mark> `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?                                                                      |

{% tabs %}
{% tab title="200 A new PushSubscription has been generated, which will send the requested alerts to your endpoint." %}

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

{% endtab %}
{% endtabs %}

## Get current subscription

<mark style="color:blue;">`GET`</mark> `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> |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}

{% tab title="404 A PushSubscription does not exist for this token." %}

```javascript
{
  "error": "Record not found"
}
```

{% endtab %}
{% endtabs %}

## Change types of notifications

<mark style="color:orange;">`PUT`</mark> `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?      |

{% tabs %}
{% tab title="200 Updating a PushSubscription to only receive mention alerts" %}

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

{% endtab %}

{% tab title="404 No existing PushSubscription for this token" %}

```javascript
{
  "error": "Record not found"
}
```

{% endtab %}
{% endtabs %}

## Remove current subscription

<mark style="color:red;">`DELETE`</mark> `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> |

{% tabs %}
{% tab title="200 PushSubscription successfully deleted or did not exist previously" %}

```javascript
{}
```

{% endtab %}
{% endtabs %}