shishantbiswas/coder
1
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2026-06-03 13:08:25 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
abe66a38ebbfe1b5489866643da1f2c9fdebea5e
coder/docs/reference/api/notifications.md
T
Susana Ferreira eec6c8c120 feat: support custom notifications (#19751) 
## Description

Adds support for sending an ad‑hoc custom notification to the
authenticated user via API and CLI. This is useful for surfacing the
result of scripts or long‑running tasks. Notifications are delivered
through the configured method and the dashboard Inbox, respecting
existing preferences and delivery settings.

## Changes

* New notification template: “Custom Notification” with a label for a
custom title and a custom message.
* New API endpoint: `POST /api/v2/notifications/custom` to send a custom
notification to the requesting user.
* New API endpoint: `GET /notifications/templates/custom` to get custom
notification template.
* New CLI subcommand: `coder notifications custom <title> <message>` to
send a custom notification to the requesting user.
* Documentation updates: Add a “Custom notifications” section under
Administration > Monitoring > Notifications, including instructions on
sending custom notifications and examples of when to use them.

Closes: https://github.com/coder/coder/issues/19611
2025-09-11 15:08:57 +02:00

23 KiB
Generated
Raw Blame History

Notifications

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 /notifications/custom

Body parameter

{
  "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

400 Response

{
  "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 /notifications/dispatch-methods

Example responses

200 Response

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

Responses

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

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.

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

200 Response

{
  "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 /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 /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
format plaintext
format markdown

Example responses

200 Response

{
  "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 /notifications/inbox/{id}/read-status

Parameters

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

Example responses

200 Response

{
  "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 /notifications/settings

Example responses

200 Response

{
  "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 /notifications/settings

Body parameter

{
  "notifier_paused": true
}

Parameters

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

Example responses

200 Response

{
  "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 /notifications/templates/custom

Example responses

200 Response

[
  {
    "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 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.

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 /notifications/templates/system

Example responses

200 Response

[
  {
    "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 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.

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 /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 /users/{user}/notifications/preferences

Parameters

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

Example responses

200 Response

[
  {
    "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 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.

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 /users/{user}/notifications/preferences

Body parameter

{
  "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

200 Response

[
  {
    "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 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.

Reference in New Issue View Git Blame Copy Permalink