# Notifications
## Send a custom notification [#send-a-custom-notification]
### Code samples [#code-samples]
```sh
# Example request using curl
curl -X POST http://coder-server:8080/api/v2/notifications/custom \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`POST /api/v2/notifications/custom`
> Body parameter
```json
{
"content": {
"message": "string",
"title": "string"
}
}
```
### Parameters [#parameters]
| Name | In | Type | Required | Description |
| ------ | ---- | --------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------ |
| `body` | body | [codersdk.CustomNotificationRequest](/beta-docs/reference/api/schemas/#codersdkcustomnotificationrequest) | true | Provide a non-empty title or message |
### Example responses [#example-responses]
> 400 Response
```json
{
"detail": "string",
"message": "string",
"validations": [
{
"detail": "string",
"field": "string"
}
]
}
```
### Responses [#responses]
| Status | Meaning | Description | Schema |
| ------ | -------------------------------------------------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------- |
| 204 | [No Content](https://tools.ietf.org/html/rfc7231#section-6.3.5) | No Content | |
| 400 | [Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1) | Invalid request body | [codersdk.Response](/beta-docs/reference/api/schemas/#codersdkresponse) |
| 403 | [Forbidden](https://tools.ietf.org/html/rfc7231#section-6.5.3) | System users cannot send custom notifications | [codersdk.Response](/beta-docs/reference/api/schemas/#codersdkresponse) |
| 500 | [Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1) | Failed to send custom notification | [codersdk.Response](/beta-docs/reference/api/schemas/#codersdkresponse) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Get notification dispatch methods [#get-notification-dispatch-methods]
### Code samples [#code-samples-1]
```sh
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/notifications/dispatch-methods \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /api/v2/notifications/dispatch-methods`
### Example responses [#example-responses-1]
> 200 Response
```json
[
{
"available": [
"string"
],
"default": "string"
}
]
```
### Responses [#responses-1]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.NotificationMethodsResponse](/beta-docs/reference/api/schemas/#codersdknotificationmethodsresponse) |
Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| -------------- | ------ | -------- | ------------ | ----------- |
| `[array item]` | array | false | | |
| `» available` | array | false | | |
| `» default` | string | false | | |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## List inbox notifications [#list-inbox-notifications]
### Code samples [#code-samples-2]
```sh
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/notifications/inbox \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /api/v2/notifications/inbox`
### Parameters [#parameters-1]
| Name | In | Type | Required | Description |
| ----------------- | ----- | ------------ | -------- | --------------------------------------------------------------------------------------------------------------- |
| `targets` | query | string | false | Comma-separated list of target IDs to filter notifications |
| `templates` | query | string | false | Comma-separated list of template IDs to filter notifications |
| `read_status` | query | string | false | Filter notifications by read status. Possible values: read, unread, all |
| `starting_before` | query | string(uuid) | false | ID of the last notification from the current page. Notifications returned will be older than the associated one |
### Example responses [#example-responses-2]
> 200 Response
```json
{
"notifications": [
{
"actions": [
{
"label": "string",
"url": "string"
}
],
"content": "string",
"created_at": "2019-08-24T14:15:22Z",
"icon": "string",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"read_at": "string",
"targets": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
"title": "string",
"user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
}
],
"unread_count": 0
}
```
### Responses [#responses-2]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.ListInboxNotificationsResponse](/beta-docs/reference/api/schemas/#codersdklistinboxnotificationsresponse) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Mark all unread notifications as read [#mark-all-unread-notifications-as-read]
### Code samples [#code-samples-3]
```sh
# Example request using curl
curl -X PUT http://coder-server:8080/api/v2/notifications/inbox/mark-all-as-read \
-H 'Coder-Session-Token: API_KEY'
```
`PUT /api/v2/notifications/inbox/mark-all-as-read`
### Responses [#responses-3]
| Status | Meaning | Description | Schema |
| ------ | --------------------------------------------------------------- | ----------- | ------ |
| 204 | [No Content](https://tools.ietf.org/html/rfc7231#section-6.3.5) | No Content | |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Watch for new inbox notifications [#watch-for-new-inbox-notifications]
### Code samples [#code-samples-4]
```sh
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/notifications/inbox/watch \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /api/v2/notifications/inbox/watch`
### Parameters [#parameters-2]
| Name | In | Type | Required | Description |
| ------------- | ----- | ------ | -------- | ----------------------------------------------------------------------- |
| `targets` | query | string | false | Comma-separated list of target IDs to filter notifications |
| `templates` | query | string | false | Comma-separated list of template IDs to filter notifications |
| `read_status` | query | string | false | Filter notifications by read status. Possible values: read, unread, all |
| `format` | query | string | false | Define the output format for notifications title and body. |
#### Enumerated Values [#enumerated-values]
| Parameter | Value(s) |
| --------- | ----------------------- |
| `format` | `markdown`, `plaintext` |
### Example responses [#example-responses-3]
> 200 Response
```json
{
"notification": {
"actions": [
{
"label": "string",
"url": "string"
}
],
"content": "string",
"created_at": "2019-08-24T14:15:22Z",
"icon": "string",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"read_at": "string",
"targets": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
"title": "string",
"user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
},
"unread_count": 0
}
```
### Responses [#responses-4]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.GetInboxNotificationResponse](/beta-docs/reference/api/schemas/#codersdkgetinboxnotificationresponse) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Update read status of a notification [#update-read-status-of-a-notification]
### Code samples [#code-samples-5]
```sh
# Example request using curl
curl -X PUT http://coder-server:8080/api/v2/notifications/inbox/{id}/read-status \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`PUT /api/v2/notifications/inbox/{id}/read-status`
### Parameters [#parameters-3]
| Name | In | Type | Required | Description |
| ---- | ---- | ------ | -------- | ---------------------- |
| `id` | path | string | true | id of the notification |
### Example responses [#example-responses-4]
> 200 Response
```json
{
"detail": "string",
"message": "string",
"validations": [
{
"detail": "string",
"field": "string"
}
]
}
```
### Responses [#responses-5]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ----------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.Response](/beta-docs/reference/api/schemas/#codersdkresponse) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Get notifications settings [#get-notifications-settings]
### Code samples [#code-samples-6]
```sh
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/notifications/settings \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /api/v2/notifications/settings`
### Example responses [#example-responses-5]
> 200 Response
```json
{
"notifier_paused": true
}
```
### Responses [#responses-6]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.NotificationsSettings](/beta-docs/reference/api/schemas/#codersdknotificationssettings) |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Update notifications settings [#update-notifications-settings]
### Code samples [#code-samples-7]
```sh
# Example request using curl
curl -X PUT http://coder-server:8080/api/v2/notifications/settings \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`PUT /api/v2/notifications/settings`
> Body parameter
```json
{
"notifier_paused": true
}
```
### Parameters [#parameters-4]
| Name | In | Type | Required | Description |
| ------ | ---- | ------------------------------------------------------------------------------------------------- | -------- | ------------------------------ |
| `body` | body | [codersdk.NotificationsSettings](/beta-docs/reference/api/schemas/#codersdknotificationssettings) | true | Notifications settings request |
### Example responses [#example-responses-6]
> 200 Response
```json
{
"notifier_paused": true
}
```
### Responses [#responses-7]
| Status | Meaning | Description | Schema |
| ------ | --------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | [codersdk.NotificationsSettings](/beta-docs/reference/api/schemas/#codersdknotificationssettings) |
| 304 | [Not Modified](https://tools.ietf.org/html/rfc7232#section-4.1) | Not Modified | |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Get custom notification templates [#get-custom-notification-templates]
### Code samples [#code-samples-8]
```sh
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/notifications/templates/custom \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /api/v2/notifications/templates/custom`
### Example responses [#example-responses-7]
> 200 Response
```json
[
{
"actions": "string",
"body_template": "string",
"enabled_by_default": true,
"group": "string",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"kind": "string",
"method": "string",
"name": "string",
"title_template": "string"
}
]
```
### Responses [#responses-8]
| Status | Meaning | Description | Schema |
| ------ | -------------------------------------------------------------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.NotificationTemplate](/beta-docs/reference/api/schemas/#codersdknotificationtemplate) |
| 500 | [Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1) | Failed to retrieve 'custom' notifications template | [codersdk.Response](/beta-docs/reference/api/schemas/#codersdkresponse) |
Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| ---------------------- | ------------ | -------- | ------------ | ----------- |
| `[array item]` | array | false | | |
| `» actions` | string | false | | |
| `» body_template` | string | false | | |
| `» enabled_by_default` | boolean | false | | |
| `» group` | string | false | | |
| `» id` | string(uuid) | false | | |
| `» kind` | string | false | | |
| `» method` | string | false | | |
| `» name` | string | false | | |
| `» title_template` | string | false | | |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Get system notification templates [#get-system-notification-templates]
### Code samples [#code-samples-9]
```sh
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/notifications/templates/system \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /api/v2/notifications/templates/system`
### Example responses [#example-responses-8]
> 200 Response
```json
[
{
"actions": "string",
"body_template": "string",
"enabled_by_default": true,
"group": "string",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"kind": "string",
"method": "string",
"name": "string",
"title_template": "string"
}
]
```
### Responses [#responses-9]
| Status | Meaning | Description | Schema |
| ------ | -------------------------------------------------------------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.NotificationTemplate](/beta-docs/reference/api/schemas/#codersdknotificationtemplate) |
| 500 | [Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1) | Failed to retrieve 'system' notifications template | [codersdk.Response](/beta-docs/reference/api/schemas/#codersdkresponse) |
Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| ---------------------- | ------------ | -------- | ------------ | ----------- |
| `[array item]` | array | false | | |
| `» actions` | string | false | | |
| `» body_template` | string | false | | |
| `» enabled_by_default` | boolean | false | | |
| `» group` | string | false | | |
| `» id` | string(uuid) | false | | |
| `» kind` | string | false | | |
| `» method` | string | false | | |
| `» name` | string | false | | |
| `» title_template` | string | false | | |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Send a test notification [#send-a-test-notification]
### Code samples [#code-samples-10]
```sh
# Example request using curl
curl -X POST http://coder-server:8080/api/v2/notifications/test \
-H 'Coder-Session-Token: API_KEY'
```
`POST /api/v2/notifications/test`
### Responses [#responses-10]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ------ |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Get user notification preferences [#get-user-notification-preferences]
### Code samples [#code-samples-11]
```sh
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/users/{user}/notifications/preferences \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`GET /api/v2/users/{user}/notifications/preferences`
### Parameters [#parameters-5]
| Name | In | Type | Required | Description |
| ------ | ---- | ------ | -------- | -------------------- |
| `user` | path | string | true | User ID, name, or me |
### Example responses [#example-responses-9]
> 200 Response
```json
[
{
"disabled": true,
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"updated_at": "2019-08-24T14:15:22Z"
}
]
```
### Responses [#responses-11]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------ |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.NotificationPreference](/beta-docs/reference/api/schemas/#codersdknotificationpreference) |
Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| -------------- | ----------------- | -------- | ------------ | ----------- |
| `[array item]` | array | false | | |
| `» disabled` | boolean | false | | |
| `» id` | string(uuid) | false | | |
| `» updated_at` | string(date-time) | false | | |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).
## Update user notification preferences [#update-user-notification-preferences]
### Code samples [#code-samples-12]
```sh
# Example request using curl
curl -X PUT http://coder-server:8080/api/v2/users/{user}/notifications/preferences \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
```
`PUT /api/v2/users/{user}/notifications/preferences`
> Body parameter
```json
{
"template_disabled_map": {
"property1": true,
"property2": true
}
}
```
### Parameters [#parameters-6]
| Name | In | Type | Required | Description |
| ------ | ---- | ------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------- |
| `user` | path | string | true | User ID, name, or me |
| `body` | body | [codersdk.UpdateUserNotificationPreferences](/beta-docs/reference/api/schemas/#codersdkupdateusernotificationpreferences) | true | Preferences |
### Example responses [#example-responses-10]
> 200 Response
```json
[
{
"disabled": true,
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"updated_at": "2019-08-24T14:15:22Z"
}
]
```
### Responses [#responses-12]
| Status | Meaning | Description | Schema |
| ------ | ------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------ |
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.NotificationPreference](/beta-docs/reference/api/schemas/#codersdknotificationpreference) |
Response Schema
Status Code **200**
| Name | Type | Required | Restrictions | Description |
| -------------- | ----------------- | -------- | ------------ | ----------- |
| `[array item]` | array | false | | |
| `» disabled` | boolean | false | | |
| `» id` | string(uuid) | false | | |
| `» updated_at` | string(date-time) | false | | |
To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).