2026-08-11 11:22:55 -04:00
---
# Code generated by make gen. DO NOT EDIT.
title : Notifications
---
<!-- DO NOT EDIT | GENERATED CONTENT -->
2024-08-05 16:18:45 +02:00
2025-09-11 15:08:57 +02:00
## Send a custom notification
### Code samples
2026-07-15 14:07:09 -04:00
```sh
2025-09-11 15:08:57 +02:00
# 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'
```
2026-05-05 02:54:03 +05:00
`POST /api/v2/notifications/custom`
2025-09-11 15:08:57 +02:00
> Body parameter
```json
{
"content" : {
"message" : "string" ,
"title" : "string"
}
}
```
### Parameters
| Name | In | Type | Required | Description |
|--------|------|------------------------------------------------------------------------------------|----------|--------------------------------------|
| `body` | body | [codersdk.CustomNotificationRequest ](schemas.md#codersdkcustomnotificationrequest ) | true | Provide a non-empty title or message |
### Example responses
> 400 Response
```json
{
"detail" : "string" ,
"message" : "string" ,
"validations" : [
{
"detail" : "string" ,
"field" : "string"
}
]
}
```
### 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 ](schemas.md#codersdkresponse ) |
| 403 | [Forbidden ](https://tools.ietf.org/html/rfc7231#section-6.5.3 ) | System users cannot send custom notifications | [codersdk.Response ](schemas.md#codersdkresponse ) |
| 500 | [Internal Server Error ](https://tools.ietf.org/html/rfc7231#section-6.6.1 ) | Failed to send custom notification | [codersdk.Response ](schemas.md#codersdkresponse ) |
To perform this operation, you must be authenticated. [Learn more ](authentication.md ).
2024-08-05 16:18:45 +02:00
## Get notification dispatch methods
### Code samples
2026-07-15 14:07:09 -04:00
```sh
2024-08-05 16:18:45 +02:00
# 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'
```
2026-05-05 02:54:03 +05:00
`GET /api/v2/notifications/dispatch-methods`
2024-08-05 16:18:45 +02:00
### Example responses
> 200 Response
```json
[
2025-01-03 18:12:59 +05:00
{
"available" : [
"string"
],
"default" : "string"
}
2024-08-05 16:18:45 +02:00
]
```
### Responses
| Status | Meaning | Description | Schema |
2025-01-03 18:12:59 +05:00
|--------|---------------------------------------------------------|-------------|-------------------------------------------------------------------------------------------------|
2024-08-05 16:18:45 +02:00
| 200 | [OK ](https://tools.ietf.org/html/rfc7231#section-6.3.1 ) | OK | array of [codersdk.NotificationMethodsResponse ](schemas.md#codersdknotificationmethodsresponse ) |
<h3 id="get-notification-dispatch-methods-responseschema">Response Schema</h3>
Status Code **200**
| Name | Type | Required | Restrictions | Description |
2025-01-03 18:12:59 +05:00
|----------------|--------|----------|--------------|-------------|
2024-08-05 16:18:45 +02:00
| `[array item]` | array | false | | |
| `» available` | array | false | | |
| `» default` | string | false | | |
To perform this operation, you must be authenticated. [Learn more ](authentication.md ).
2025-03-18 00:02:47 +01:00
## List inbox notifications
### Code samples
2026-07-15 14:07:09 -04:00
```sh
2025-03-18 00:02:47 +01:00
# 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'
```
2026-05-05 02:54:03 +05:00
`GET /api/v2/notifications/inbox`
2025-03-18 00:02:47 +01:00
### Parameters
2025-03-21 16:41:13 +01:00
| 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 |
2025-03-18 00:02:47 +01:00
### Example responses
> 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
| Status | Meaning | Description | Schema |
|--------|---------------------------------------------------------|-------------|----------------------------------------------------------------------------------------------|
| 200 | [OK ](https://tools.ietf.org/html/rfc7231#section-6.3.1 ) | OK | [codersdk.ListInboxNotificationsResponse ](schemas.md#codersdklistinboxnotificationsresponse ) |
To perform this operation, you must be authenticated. [Learn more ](authentication.md ).
2025-03-20 13:41:54 +01:00
## Mark all unread notifications as read
### Code samples
2026-07-15 14:07:09 -04:00
```sh
2025-03-20 13:41:54 +01:00
# 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'
```
2026-05-05 02:54:03 +05:00
`PUT /api/v2/notifications/inbox/mark-all-as-read`
2025-03-20 13:41:54 +01:00
### Responses
| 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 ](authentication.md ).
2025-03-18 00:02:47 +01:00
## Watch for new inbox notifications
### Code samples
2026-07-15 14:07:09 -04:00
```sh
2025-03-18 00:02:47 +01:00
# 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'
```
2026-05-05 02:54:03 +05:00
`GET /api/v2/notifications/inbox/watch`
2025-03-18 00:02:47 +01:00
### Parameters
| 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 |
2025-03-21 16:41:13 +01:00
| `format` | query | string | false | Define the output format for notifications title and body. |
#### Enumerated Values
2025-12-22 16:19:25 +01:00
| Parameter | Value(s) |
|-----------|-------------------------|
| `format` | `markdown` , `plaintext` |
2025-03-18 00:02:47 +01:00
### Example responses
> 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
| Status | Meaning | Description | Schema |
|--------|---------------------------------------------------------|-------------|------------------------------------------------------------------------------------------|
| 200 | [OK ](https://tools.ietf.org/html/rfc7231#section-6.3.1 ) | OK | [codersdk.GetInboxNotificationResponse ](schemas.md#codersdkgetinboxnotificationresponse ) |
To perform this operation, you must be authenticated. [Learn more ](authentication.md ).
## Update read status of a notification
### Code samples
2026-07-15 14:07:09 -04:00
```sh
2025-03-18 00:02:47 +01:00
# 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'
```
2026-05-05 02:54:03 +05:00
`PUT /api/v2/notifications/inbox/{id}/read-status`
2025-03-18 00:02:47 +01:00
### Parameters
| Name | In | Type | Required | Description |
|------|------|--------|----------|------------------------|
| `id` | path | string | true | id of the notification |
### Example responses
> 200 Response
```json
{
"detail" : "string" ,
"message" : "string" ,
"validations" : [
{
"detail" : "string" ,
"field" : "string"
}
]
}
```
### Responses
| Status | Meaning | Description | Schema |
|--------|---------------------------------------------------------|-------------|--------------------------------------------------|
| 200 | [OK ](https://tools.ietf.org/html/rfc7231#section-6.3.1 ) | OK | [codersdk.Response ](schemas.md#codersdkresponse ) |
To perform this operation, you must be authenticated. [Learn more ](authentication.md ).
2024-08-05 16:18:45 +02:00
## Get notifications settings
### Code samples
2026-07-15 14:07:09 -04:00
```sh
2024-08-05 16:18:45 +02:00
# 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'
```
2026-05-05 02:54:03 +05:00
`GET /api/v2/notifications/settings`
2024-08-05 16:18:45 +02:00
### Example responses
> 200 Response
```json
{
2025-01-03 18:12:59 +05:00
"notifier_paused" : true
2024-08-05 16:18:45 +02:00
}
```
### Responses
| Status | Meaning | Description | Schema |
2025-01-03 18:12:59 +05:00
|--------|---------------------------------------------------------|-------------|----------------------------------------------------------------------------|
2024-08-05 16:18:45 +02:00
| 200 | [OK ](https://tools.ietf.org/html/rfc7231#section-6.3.1 ) | OK | [codersdk.NotificationsSettings ](schemas.md#codersdknotificationssettings ) |
To perform this operation, you must be authenticated. [Learn more ](authentication.md ).
## Update notifications settings
### Code samples
2026-07-15 14:07:09 -04:00
```sh
2024-08-05 16:18:45 +02:00
# 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'
```
2026-05-05 02:54:03 +05:00
`PUT /api/v2/notifications/settings`
2024-08-05 16:18:45 +02:00
> Body parameter
```json
{
2025-01-03 18:12:59 +05:00
"notifier_paused" : true
2024-08-05 16:18:45 +02:00
}
```
### Parameters
| Name | In | Type | Required | Description |
2025-01-03 18:12:59 +05:00
|--------|------|----------------------------------------------------------------------------|----------|--------------------------------|
2024-08-05 16:18:45 +02:00
| `body` | body | [codersdk.NotificationsSettings ](schemas.md#codersdknotificationssettings ) | true | Notifications settings request |
### Example responses
> 200 Response
```json
{
2025-01-03 18:12:59 +05:00
"notifier_paused" : true
2024-08-05 16:18:45 +02:00
}
```
### Responses
| Status | Meaning | Description | Schema |
2025-01-03 18:12:59 +05:00
|--------|-----------------------------------------------------------------|--------------|----------------------------------------------------------------------------|
2024-08-05 16:18:45 +02:00
| 200 | [OK ](https://tools.ietf.org/html/rfc7231#section-6.3.1 ) | OK | [codersdk.NotificationsSettings ](schemas.md#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 ](authentication.md ).
2025-09-11 15:08:57 +02:00
## Get custom notification templates
### Code samples
2026-07-15 14:07:09 -04:00
```sh
2025-09-11 15:08:57 +02:00
# 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'
```
2026-05-05 02:54:03 +05:00
`GET /api/v2/notifications/templates/custom`
2025-09-11 15:08:57 +02:00
### Example responses
> 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
| Status | Meaning | Description | Schema |
|--------|----------------------------------------------------------------------------|----------------------------------------------------|-----------------------------------------------------------------------------------|
| 200 | [OK ](https://tools.ietf.org/html/rfc7231#section-6.3.1 ) | OK | array of [codersdk.NotificationTemplate ](schemas.md#codersdknotificationtemplate ) |
| 500 | [Internal Server Error ](https://tools.ietf.org/html/rfc7231#section-6.6.1 ) | Failed to retrieve 'custom' notifications template | [codersdk.Response ](schemas.md#codersdkresponse ) |
<h3 id="get-custom-notification-templates-responseschema">Response Schema</h3>
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 ](authentication.md ).
2024-08-05 16:18:45 +02:00
## Get system notification templates
### Code samples
2026-07-15 14:07:09 -04:00
```sh
2024-08-05 16:18:45 +02:00
# 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'
```
2026-05-05 02:54:03 +05:00
`GET /api/v2/notifications/templates/system`
2024-08-05 16:18:45 +02:00
### Example responses
> 200 Response
```json
[
2025-01-03 18:12:59 +05:00
{
"actions" : "string" ,
"body_template" : "string" ,
2025-01-13 15:01:47 +00:00
"enabled_by_default" : true ,
2025-01-03 18:12:59 +05:00
"group" : "string" ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"kind" : "string" ,
"method" : "string" ,
"name" : "string" ,
"title_template" : "string"
}
2024-08-05 16:18:45 +02:00
]
```
### Responses
2025-09-11 15:08:57 +02:00
| Status | Meaning | Description | Schema |
|--------|----------------------------------------------------------------------------|----------------------------------------------------|-----------------------------------------------------------------------------------|
| 200 | [OK ](https://tools.ietf.org/html/rfc7231#section-6.3.1 ) | OK | array of [codersdk.NotificationTemplate ](schemas.md#codersdknotificationtemplate ) |
| 500 | [Internal Server Error ](https://tools.ietf.org/html/rfc7231#section-6.6.1 ) | Failed to retrieve 'system' notifications template | [codersdk.Response ](schemas.md#codersdkresponse ) |
2024-08-05 16:18:45 +02:00
<h3 id="get-system-notification-templates-responseschema">Response Schema</h3>
Status Code **200**
2025-01-13 15:01:47 +00:00
| 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 | | |
2024-08-05 16:18:45 +02:00
To perform this operation, you must be authenticated. [Learn more ](authentication.md ).
2025-02-19 14:08:38 +01:00
## Send a test notification
### Code samples
2026-07-15 14:07:09 -04:00
```sh
2025-02-19 14:08:38 +01:00
# Example request using curl
curl -X POST http://coder-server:8080/api/v2/notifications/test \
-H 'Coder-Session-Token: API_KEY'
```
2026-05-05 02:54:03 +05:00
`POST /api/v2/notifications/test`
2025-02-19 14:08:38 +01:00
### Responses
| 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 ](authentication.md ).
2024-08-05 16:18:45 +02:00
## Get user notification preferences
### Code samples
2026-07-15 14:07:09 -04:00
```sh
2024-08-05 16:18:45 +02:00
# 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'
```
2026-05-05 02:54:03 +05:00
`GET /api/v2/users/{user}/notifications/preferences`
2024-08-05 16:18:45 +02:00
### Parameters
| Name | In | Type | Required | Description |
2025-01-03 18:12:59 +05:00
|--------|------|--------|----------|----------------------|
2024-08-05 16:18:45 +02:00
| `user` | path | string | true | User ID, name, or me |
### Example responses
> 200 Response
```json
[
2025-01-03 18:12:59 +05:00
{
"disabled" : true ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"updated_at" : "2019-08-24T14:15:22Z"
}
2024-08-05 16:18:45 +02:00
]
```
### Responses
| Status | Meaning | Description | Schema |
2025-01-03 18:12:59 +05:00
|--------|---------------------------------------------------------|-------------|---------------------------------------------------------------------------------------|
2024-08-05 16:18:45 +02:00
| 200 | [OK ](https://tools.ietf.org/html/rfc7231#section-6.3.1 ) | OK | array of [codersdk.NotificationPreference ](schemas.md#codersdknotificationpreference ) |
<h3 id="get-user-notification-preferences-responseschema">Response Schema</h3>
Status Code **200**
| Name | Type | Required | Restrictions | Description |
2025-01-03 18:12:59 +05:00
|----------------|-------------------|----------|--------------|-------------|
2024-08-05 16:18:45 +02:00
| `[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 ](authentication.md ).
## Update user notification preferences
### Code samples
2026-07-15 14:07:09 -04:00
```sh
2024-08-05 16:18:45 +02:00
# 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'
```
2026-05-05 02:54:03 +05:00
`PUT /api/v2/users/{user}/notifications/preferences`
2024-08-05 16:18:45 +02:00
> Body parameter
```json
{
2025-01-03 18:12:59 +05:00
"template_disabled_map" : {
"property1" : true ,
"property2" : true
}
2024-08-05 16:18:45 +02:00
}
```
### Parameters
| Name | In | Type | Required | Description |
2025-01-03 18:12:59 +05:00
|--------|------|----------------------------------------------------------------------------------------------------|----------|----------------------|
2024-08-05 16:18:45 +02:00
| `user` | path | string | true | User ID, name, or me |
| `body` | body | [codersdk.UpdateUserNotificationPreferences ](schemas.md#codersdkupdateusernotificationpreferences ) | true | Preferences |
### Example responses
> 200 Response
```json
[
2025-01-03 18:12:59 +05:00
{
"disabled" : true ,
"id" : "497f6eca-6276-4993-bfeb-53cbbbba6f08" ,
"updated_at" : "2019-08-24T14:15:22Z"
}
2024-08-05 16:18:45 +02:00
]
```
### Responses
| Status | Meaning | Description | Schema |
2025-01-03 18:12:59 +05:00
|--------|---------------------------------------------------------|-------------|---------------------------------------------------------------------------------------|
2024-08-05 16:18:45 +02:00
| 200 | [OK ](https://tools.ietf.org/html/rfc7231#section-6.3.1 ) | OK | array of [codersdk.NotificationPreference ](schemas.md#codersdknotificationpreference ) |
<h3 id="update-user-notification-preferences-responseschema">Response Schema</h3>
Status Code **200**
| Name | Type | Required | Restrictions | Description |
2025-01-03 18:12:59 +05:00
|----------------|-------------------|----------|--------------|-------------|
2024-08-05 16:18:45 +02:00
| `[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 ](authentication.md ).