notifications.md 4.07 KB
Newer Older
Eugen Rochko's avatar
Eugen Rochko committed
1
---
Eugen Rochko's avatar
Eugen Rochko committed
2
title: Notifications
Eugen Rochko's avatar
Eugen Rochko committed
3 4
menu:
  docs:
Eugen Rochko's avatar
Eugen Rochko committed
5
    parent: rest-api
Eugen Rochko's avatar
Eugen Rochko committed
6 7
    weight: 10
---
Eugen Rochko's avatar
Eugen Rochko committed
8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119

## GET /api/v1/notifications

Notifications concerning the user.

Returns array of [Notification]({{< relref "entities.md#notification" >}})

### Resource information

{{< api_method_info auth="Yes" user="Yes" scope="read read:notifications" version="0.0.0" >}}

### Parameters

|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `max_id` | Return results older than ID | Optional ||
| `since_id` | Return results newer than ID | Optional ||
| `limit` | Maximum number of results | Optional | 20 |
| `exclude_types` | Array of types to exclude (e.g. `follow`, `favourite`, `reblog`, `mention`) | Optional ||

### Pagination

{{< api_dynamic_pagination >}}

## GET /api/v1/notifications/:id

Returns [Notification]({{< relref "entities.md#notification" >}})

### Resource information

{{< api_method_info auth="Yes" user="Yes" scope="read read:notifications" version="0.0.0" >}}

## POST /api/v1/notifications/clear

Delete all notifications from the server.

### Resource information

{{< api_method_info auth="Yes" user="Yes" scope="write write:notifications" version="0.0.0" >}}

## POST /api/v1/notifications/dismiss

Delete a single notification from the server.

### Resource information

{{< api_method_info auth="Yes" user="Yes" scope="write write:notifications" version="0.0.0" >}}

### Parameters

|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `id` | Notification ID | Required ||

## POST /api/v1/push/subscription

Add a Web Push API subscription to receive notifications. See also: [Web Push API]({{< relref "push.md" >}})

> Each access token can have one push subscription. If you create a new subscription, the old subscription is deleted.

Returns [Push Subscription]({{< relref "entities.md#push-subscription" >}})

### Resource information

{{< api_method_info auth="Yes" user="Yes" scope="push" version="0.0.0" >}}

### Parameters

|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `subscription[endpoint]` | Endpoint URL that called when notification is happen. | Required ||
| `subscription[keys][p256dh]` | User agent public key. Base64 encoded string of public key of ECDH key using 'prime256v1' curve. | Required ||
| `subscription[keys][auth]` | Auth secret. Base64 encoded string of 16 bytes of random data. | Required ||
| `data[alerts][follow]` | Boolean of whether you want to receive follow notification event. | Optional ||
| `data[alerts][favourite]` | Boolean of whether you want to receive favourite notification event. | Optional ||
| `data[alerts][reblog]` | Boolean of whether you want to receive reblog notification event. | Optional ||
| `data[alerts][mention]` | Boolean of whether you want to receive mention notification event. | Optional ||

## GET /api/v1/push/subscription

Returns [Push Subscription]({{< relref "entities.md#push-subscription" >}})

### Resource information

{{< api_method_info auth="Yes" user="Yes" scope="push" version="0.0.0" >}}

## PUT /api/v1/push/subscription

Update current Web Push API subscription. Only the `data` part can be updated, e.g. which types of notifications are desired. To change fundamentals, a new subscription must be created instead.

Returns [Push Subscription]({{< relref "entities.md#push-subscription" >}})

### Resource information

{{< api_method_info auth="Yes" user="Yes" scope="push" version="0.0.0" >}}

### Parameters

|Name|Description|Required|Default|
|----|-----------|:------:|:-----:|
| `data[alerts][follow]` | Boolean of whether you want to receive follow notification event. | Optional ||
| `data[alerts][favourite]` | Boolean of whether you want to receive favourite notification event. | Optional ||
| `data[alerts][reblog]` | Boolean of whether you want to receive reblog notification event. | Optional ||
| `data[alerts][mention]` | Boolean of whether you want to receive mention notification event. | Optional ||

## DELETE /api/v1/push/subscription

Remove the current Web Push API subscription.

### Resource information

{{< api_method_info auth="Yes" user="Yes" scope="push" version="0.0.0" >}}