notifications.md 4.16 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 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59

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

Eugen Rochko's avatar
Eugen Rochko committed
60 61 62
|Name|Description|Required|
|----|-----------|:------:|
| `id` | Notification ID | Required |
Eugen Rochko's avatar
Eugen Rochko committed
63 64 65 66 67 68 69 70 71 72 73

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

74
{{< api_method_info auth="Yes" user="Yes" scope="push" version="2.4.0" >}}
Eugen Rochko's avatar
Eugen Rochko committed
75 76 77

### Parameters

Eugen Rochko's avatar
Eugen Rochko committed
78 79 80 81 82 83 84 85 86
|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 |
Eugen Rochko's avatar
Eugen Rochko committed
87 88 89 90 91 92 93

## GET /api/v1/push/subscription

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

### Resource information

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

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

104
{{< api_method_info auth="Yes" user="Yes" scope="push" version="2.4.0" >}}
Eugen Rochko's avatar
Eugen Rochko committed
105 106 107

### Parameters

Eugen Rochko's avatar
Eugen Rochko committed
108 109 110 111 112 113
|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 |
Eugen Rochko's avatar
Eugen Rochko committed
114 115 116 117 118 119 120

## DELETE /api/v1/push/subscription

Remove the current Web Push API subscription.

### Resource information

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