# Kiteworks API — notifications Operations

**3 endpoints** | [Browse interactive reference](https://developer.kiteworks.com/api-reference/notifications.html) | [Download spec slice](https://developer.kiteworks.com/assets/specs/notifications.json)

> **Authentication required.** All requests must include a Bearer access token in the
> `Authorization` header. See [Authentication](https://developer.kiteworks.com/authentication.md) for how to
> obtain a token using OAuth 2.0 Authorization Code (PKCE) or JWT Bearer flow.

---

## PUT /rest/folders/{id}/actions/setNotifications

**Summary:** Set/Update notifications

Creates or updates the current user's notification subscription for the specified folder. Optionally applies the same settings to all nested subfolders. Returns HTTP 201 if a new subscription was created, or HTTP 200 if an existing one was updated.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier of the folder. |
| `includeNested` | query | no | Set notification for nested folders as well |
| `offset` | query | no | Offset |
| `limit` | query | no | Limit |
| `mode` | query | no | Determines the detail level of the response body. |

**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `fileAdded` | integer | no | Number of files added to the notification |
| `commentAdded` | integer | no | Number of comments added to the notification |
| `addLinks` | boolean | no | Indicates whether HATEOAS links should be included in the response |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Notification subscription set successfully. |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INPUT_NOT_INTEGER |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (NotificationSet):**

```json
{
  "objectId": "f0e1d2c3-b4a5-6789-0fed-cba987654321",
  "userId": "u1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "fileAdded": 1,
  "commentAdded": 1
}
```

**422 (ERR_INPUT_NOT_INTEGER):**

```json
{
  "errors": {
    "code": "ERR_INPUT_NOT_INTEGER",
    "message": "Input is not a valid integer"
  }
}
```

**Code Samples:**

**cURL:**

```shell
curl -X PUT \
  "https://{instance}.kiteworks.com/rest/folders/:id/actions/setNotifications" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "fileAdded": 1,
         "commentAdded": 1,
         "addLinks": true
       }'
```

**Python:**

```python
import requests

id = "VALUE"  # The unique identifier of the folder.

url = f"https://{{instance}}.kiteworks.com/rest/folders/{id}/actions/setNotifications"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "fileAdded": 1,
  "commentAdded": 1,
  "addLinks": true
}
response = requests.put(url, headers=headers, json=payload)
print(response.json())
```

---

## GET /rest/notifications

**Summary:** List notifications

Returns a paginated list of notification subscriptions for the current user, including the folder each subscription is for and the enabled notification types.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `userId` | query | no | Filter notifications by the ID of the user who receives them. |
| `userId:in` | query | no | Filter notifications by the ID of the user who receives them.. Search for results that match any of the specified values for this parameter. |
| `objectId` | query | no | Filter notifications by the ID of the folder they are associated with. |
| `objectId:in` | query | no | Filter notifications by the ID of the folder they are associated with.. Search for results that match any of the specified values for this parameter. |
| `fileAdded` | query | no | Filter notifications triggered when a file is added. |
| `commentAdded` | query | no | Filter notifications triggered when a comment is added. |
| `orderBy` | query | no | Sorting options |
| `offset` | query | no | Offset |
| `limit` | query | no | Limit |
| `with` | query | no | With parameters |
| `mode` | query | no | Determines the detail level of the response body. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | List of notification subscriptions retrieved successfully. |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (NotificationList):**

```json
{
  "data": [
    {
      "objectId": "f0e1d2c3-b4a5-6789-0fed-cba987654321",
      "userId": "u1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "fileAdded": 1,
      "commentAdded": 0
    }
  ],
  "metadata": {
    "total": 1,
    "limit": 50,
    "offset": 0
  }
}
```

**Code Samples:**

**cURL:**

```shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/notifications" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/notifications"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```

---

## DELETE /rest/notifications/{object_id}

**Summary:** Remove notification options

Unsubscribes the current user from all notifications for the specified folder.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `object_id` | path | yes | Object ID of the folder to remove notification options |

**Responses:**

| Code | Description |
|------|-------------|
| 204 | Notification subscription removed successfully. |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 490 | Request blocked by WAF |

**Response Examples:**

**403 (ERR_ACCESS_USER):**

```json
{
  "errors": {
    "code": "ERR_ACCESS_USER",
    "message": "Insufficient access permissions"
  }
}
```

**Code Samples:**

**cURL:**

```shell
curl -X DELETE \
  "https://{instance}.kiteworks.com/rest/notifications/:object_id" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

object_id = "VALUE"  # Object ID of the folder to remove notification options

url = f"https://{{instance}}.kiteworks.com/rest/notifications/{object_id}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.delete(url, headers=headers)
print(response.json())
```

---