notifications.md 4.08 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 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
| `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

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

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

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

### Parameters

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

## GET /api/v1/push/subscription

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

### Resource information

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

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

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

### Parameters

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

## DELETE /api/v1/push/subscription

Remove the current Web Push API subscription.

### Resource information

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