Notifications

On this page

Send a custom notification

Code samples

# 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

{
  "content": {
    "message": "string",
    "title": "string"
  }
}

Parameters

Name	In	Type	Required	Description
`body`	body	codersdk.CustomNotificationRequest	true	Provide a non-empty title or message

Example responses

{
  "detail": "string",
  "message": "string",
  "validations": [
    {
      "detail": "string",
      "field": "string"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
204	No Content	No Content
400	Bad Request	Invalid request body	codersdk.Response
403	Forbidden	System users cannot send custom notifications	codersdk.Response
500	Internal Server Error	Failed to send custom notification	codersdk.Response

To perform this operation, you must be authenticated. Learn more.

Get notification dispatch methods

Code samples

# 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

[
  {
    "available": [
      "string"
    ],
    "default": "string"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	OK	array of codersdk.NotificationMethodsResponse

Response Schema

Status Code 200

Name	Type	Required
`[array item]`	array	false
`» available`	array	false
`» default`	string	false

To perform this operation, you must be authenticated. Learn more.

List inbox notifications

Code samples

# 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

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

{
  "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	OK	codersdk.ListInboxNotificationsResponse

To perform this operation, you must be authenticated. Learn more.

Mark all unread notifications as read

Code samples

# 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

Status	Meaning	Description	Schema
204	No Content	No Content

To perform this operation, you must be authenticated. Learn more.

Watch for new inbox notifications

Code samples

# 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

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

Parameter	Value(s)
`format`	`markdown`, `plaintext`

Example responses

{
  "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	OK	codersdk.GetInboxNotificationResponse

To perform this operation, you must be authenticated. Learn more.

Update read status of a notification

Code samples

# 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

Name	In	Type	Required	Description
`id`	path	string	true	id of the notification

Example responses

{
  "detail": "string",
  "message": "string",
  "validations": [
    {
      "detail": "string",
      "field": "string"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	codersdk.Response

To perform this operation, you must be authenticated. Learn more.

Get notifications settings

Code samples

# 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

{
  "notifier_paused": true
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	codersdk.NotificationsSettings

To perform this operation, you must be authenticated. Learn more.

Update notifications settings

Code samples

# 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

{
  "notifier_paused": true
}

Parameters

Name	In	Type	Required	Description
`body`	body	codersdk.NotificationsSettings	true	Notifications settings request

Example responses

{
  "notifier_paused": true
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	codersdk.NotificationsSettings
304	Not Modified	Not Modified

To perform this operation, you must be authenticated. Learn more.

Get custom notification templates

Code samples

# 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

[
  {
    "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	OK	array of codersdk.NotificationTemplate
500	Internal Server Error	Failed to retrieve 'custom' notifications template	codersdk.Response

Response Schema

Status Code 200

Name	Type	Required
`[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.

Get system notification templates

Code samples

# 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

[
  {
    "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	OK	array of codersdk.NotificationTemplate
500	Internal Server Error	Failed to retrieve 'system' notifications template	codersdk.Response

Response Schema

Status Code 200

Name	Type	Required
`[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.

Send a test notification

Code samples

# 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

Status	Meaning	Description	Schema
200	OK	OK

To perform this operation, you must be authenticated. Learn more.

Get user notification preferences

Code samples

# 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

Name	In	Type	Required	Description
`user`	path	string	true	User ID, name, or me

Example responses

[
  {
    "disabled": true,
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "updated_at": "2019-08-24T14:15:22Z"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	OK	array of codersdk.NotificationPreference

Response Schema

Status Code 200

Name	Type	Required
`[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.

Update user notification preferences

Code samples

# 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

{
  "template_disabled_map": {
    "property1": true,
    "property2": true
  }
}

Parameters

Name	In	Type	Required	Description
`user`	path	string	true	User ID, name, or me
`body`	body	codersdk.UpdateUserNotificationPreferences	true	Preferences

Example responses

[
  {
    "disabled": true,
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "updated_at": "2019-08-24T14:15:22Z"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	OK	array of codersdk.NotificationPreference

Response Schema

Status Code 200

Name	Type	Required
`[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.