notifications.md 4.27 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

## 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 ||
Eugen Rochko's avatar
Eugen Rochko committed
25
| `min_id` | Return results immediately newer than ID | Optional ||
Eugen Rochko's avatar
Eugen Rochko committed
26 27
| `limit` | Maximum number of results | Optional | 20 |
| `exclude_types` | Array of types to exclude (e.g. `follow`, `favourite`, `reblog`, `mention`) | Optional ||
Eugen Rochko's avatar
Eugen Rochko committed
28
| `account_id` | Return only notifications sent from given account | Optional ||
Eugen Rochko's avatar
Eugen Rochko committed
29 30 31 32 33 34 35 36 37 38 39 40 41

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

42
## POST /api/v1/notifications/:id/dismiss
Eugen Rochko's avatar
Eugen Rochko committed
43

44
Delete a single notification from the server.
Eugen Rochko's avatar
Eugen Rochko committed
45 46 47 48 49

### Resource information

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

50
## POST /api/v1/notifications/clear
Eugen Rochko's avatar
Eugen Rochko committed
51

52
Delete all notifications from the server.
Eugen Rochko's avatar
Eugen Rochko committed
53 54 55 56 57 58 59 60 61 62 63 64 65 66 67

### Resource information

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

## 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

68
{{< api_method_info auth="Yes" user="Yes" scope="push" version="2.4.0" >}}
Eugen Rochko's avatar
Eugen Rochko committed
69 70 71

### Parameters

Eugen Rochko's avatar
Eugen Rochko committed
72 73 74 75 76 77 78 79 80
|Name|Description|Required|
|----|-----------|:------:|
| `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 |
81
| `data[alerts][poll]` | Boolean of whether you want to receive poll result notification event. | Optional |
Eugen Rochko's avatar
Eugen Rochko committed
82 83 84 85 86 87 88

## GET /api/v1/push/subscription

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

### Resource information

89
{{< api_method_info auth="Yes" user="Yes" scope="push" version="2.4.0" >}}
Eugen Rochko's avatar
Eugen Rochko committed
90 91 92 93 94 95 96 97 98

## 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

99
{{< api_method_info auth="Yes" user="Yes" scope="push" version="2.4.0" >}}
Eugen Rochko's avatar
Eugen Rochko committed
100 101 102

### Parameters

Eugen Rochko's avatar
Eugen Rochko committed
103 104 105 106 107 108
|Name|Description|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 |
109
| `data[alerts][poll]` | Boolean of whether you want to receive poll result notification event. | Optional |
Eugen Rochko's avatar
Eugen Rochko committed
110 111 112 113 114 115 116

## DELETE /api/v1/push/subscription

Remove the current Web Push API subscription.

### Resource information

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