synced/coder
1
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2025-07-06 15:41:45 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
c06ef7c1eb45a129ca47cdfeaf75e853e6cee95b
coder/docs/reference/api/notifications.md
Vincent Vielle 82e37732ea feat(coderd): add format option to inbox notifications watch endpoint (#17034) 
This PR aims to allow clients to use different format for the title and
content of inbox notifications - on the watch endpoint.

This solution will help to have it working and formatted differently on
VSCode, WebUI ...
[Related to this issue](https://github.com/coder/internal/issues/523)
2025-03-21 16:41:13 +01:00

18 KiB
Generated
Raw Blame History

Notifications

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

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.